Re: [racket-users] How to fix typos in documentation?

[Gustavo Massaccesi]

I just want to clarify that if someone finds an error in the docs or a bug,
it's perfectly fine to just send a bug report:

* Inside Racket: Go to the menu > About > Submit Bug Report ...

* In Github: Submit an "Issue"

Please include enough information to reproduce the bug. For example for a
typo in the docs, I like a link to the online page of the documentation
where the typo was found, so it's completely obvious where the error is.

Someone will read the report, and make the correction. (It may take a few
month, until the next release, for the change to be visible in the online
docs.) After fixing the error, I like to reply with a link the commit that
fix the error. You can read the commit and try to understand which file was
modified, and perhaps next time send a pull request with the fix.

In the long run, it's better if you can send a pull request as discussed in
the previous messages, but every bug report with enough information is very
useful.

Gustavo

-- 
You received this message because you are subscribed to the Google Groups 
"Racket Users" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to racket-users+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: [racket-users] How to fix typos in documentation?

[Marc Kaufmann]

I agree with Greg that such a feature would be neat - so it's great that
Ben and Kieran are on it already. (Thanks!)

The CONTRIBUTING.md is a good idea (and I David's version). The 'Edit on
Github' button would solve the first stumbling block I hit, while the
contribution.md file helps later in the process.

Cheers,
Marc

On Fri, Mar 8, 2019 at 10:55 PM Ben Greenman 
wrote:

> On 3/8/19, David Storrs  wrote:
> > On Fri, Mar 8, 2019 at 3:13 PM Greg Hendershott <
> greghendersh...@gmail.com>
> > wrote:
> >
> >> I have a dumb question. Why can't doc pages have links whose label is
> >> something like "Want to improve the docs?", and the URL goes directly
> >> to the appropriate .scrbl file on GitHub?
> >>
> >
> > I asked about this a year or so ago and the consensus was that it was
> > impractically difficult given the number of tuits that were available at
> > the time.  IIRC, it would have required significant changes to the
> > documentation generation system.  Perhaps I'm misremembering, or perhaps
> > that's changed?
>
> Here's a Scribble issue about adding links to the doc pages:
>
> https://github.com/racket/scribble/issues/76
>
>
> And here's a Scribble branch that Kieran Hardy and I started (at
> RacketCon 2017) to add the links:
>
> https://github.com/bennn/scribble/commits/view-source
>
> Next month I'll try to turn the branch into a pull request. If someone
> wants to take the lead this month, feel free.
>
> --
> You received this message because you are subscribed to a topic in the
> Google Groups "Racket Users" group.
> To unsubscribe from this topic, visit
> https://groups.google.com/d/topic/racket-users/J8ylMGGGr-8/unsubscribe.
> To unsubscribe from this group and all its topics, send an email to
> racket-users+unsubscr...@googlegroups.com.
> For more options, visit https://groups.google.com/d/optout.
>

-- 
You received this message because you are subscribed to the Google Groups 
"Racket Users" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to racket-users+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: [racket-users] How to fix typos in documentation?

[Ben Greenman]

On 3/8/19, David Storrs  wrote:
> On Fri, Mar 8, 2019 at 3:13 PM Greg Hendershott 
> wrote:
>
>> I have a dumb question. Why can't doc pages have links whose label is
>> something like "Want to improve the docs?", and the URL goes directly
>> to the appropriate .scrbl file on GitHub?
>>
>
> I asked about this a year or so ago and the consensus was that it was
> impractically difficult given the number of tuits that were available at
> the time.  IIRC, it would have required significant changes to the
> documentation generation system.  Perhaps I'm misremembering, or perhaps
> that's changed?

Here's a Scribble issue about adding links to the doc pages:

https://github.com/racket/scribble/issues/76


And here's a Scribble branch that Kieran Hardy and I started (at
RacketCon 2017) to add the links:

https://github.com/bennn/scribble/commits/view-source

Next month I'll try to turn the branch into a pull request. If someone
wants to take the lead this month, feel free.

-- 
You received this message because you are subscribed to the Google Groups 
"Racket Users" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to racket-users+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: [racket-users] How to fix typos in documentation?

[David Storrs]

On Fri, Mar 8, 2019 at 3:13 PM Greg Hendershott 
wrote:

> I have a dumb question. Why can't doc pages have links whose label is
> something like "Want to improve the docs?", and the URL goes directly
> to the appropriate .scrbl file on GitHub?
>

I asked about this a year or so ago and the consensus was that it was
impractically difficult given the number of tuits that were available at
the time.  IIRC, it would have required significant changes to the
documentation generation system.  Perhaps I'm misremembering, or perhaps
that's changed?

-- 
You received this message because you are subscribed to the Google Groups 
"Racket Users" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to racket-users+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: [racket-users] How to fix typos in documentation?

[David Storrs]

Thank you for that writeup, Marc.  I've wanted to offer doc changes several
times but never had the spoons to figure out how.


Matthew, I think you're absolutely right: putting this in a CONTRIBUTING
file would be great.  I've created one and submitted a pull request.  :>

On Fri, Mar 8, 2019 at 11:52 AM Matthew Butterick  wrote:

> Perhaps this would be good material for a CONTRIBUTING.md at the top level
> of the repo, where it would be more likely to be found by future
> contributors. GitHub will automatically show a link to the file at arguably
> appropriate times. [1]
>
> [1] https://github.blog/2012-09-17-contributing-guidelines/
>
> > On Mar 8, 2019, at 8:44 AM, Marc Kaufmann 
> wrote:
> >
> > Let me (ab)use this thread to add some more details on how to submit
> pull requests (PR) on GitHub to racket using the GitHub web interface for
> other noobs - which includes myself in another month or two. Ideally I
> would write this up elsewhere to help with onboarding, but that won't
> happen soon, so here we go. We are talking ELI5 (Explain Like I'm 5) level
> explanations, so this will be painfully obvious to the vast majority
> (although it would be good for someone who knows what they are doing to
> correct whatever kludgy workflow I've come up with). I copy most of the
> steps from Paulo earlier, but add some that I still had to figure out.
>
> --
> You received this message because you are subscribed to the Google Groups
> "Racket Users" group.
> To unsubscribe from this group and stop receiving emails from it, send an
> email to racket-users+unsubscr...@googlegroups.com.
> For more options, visit https://groups.google.com/d/optout.
>

-- 
You received this message because you are subscribed to the Google Groups 
"Racket Users" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to racket-users+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: [racket-users] How to fix typos in documentation?

[Greg Hendershott]

I have a dumb question. Why can't doc pages have links whose label is
something like "Want to improve the docs?", and the URL goes directly
to the appropriate .scrbl file on GitHub?

- A .scrbl file knows its own syntax source file path.
- defmodule forms know how to make links to the package server.
- The package server has a catalog that knows where the source repo is.
- Often it knows, when a pkg is split -{lib doc test}, where the -doc
repo for a -lib is (although ironically "Documentation" for
scribble-lib is blank when I check now.)

Could these elements be combined to provide the direct link on the doc page?

Admittedly people still need to know how to use GitHub and do a PR.
But I think in my own case, the main speed bump feels like finding the
scrbl file to modify. If that were one click, I'd be more likely to
act even on low ROI tiny prose typos I might notice.

On Fri, Mar 8, 2019 at 11:52 AM Matthew Butterick  wrote:
>
> Perhaps this would be good material for a CONTRIBUTING.md at the top level of 
> the repo, where it would be more likely to be found by future contributors. 
> GitHub will automatically show a link to the file at arguably appropriate 
> times. [1]
>
> [1] https://github.blog/2012-09-17-contributing-guidelines/
>
> > On Mar 8, 2019, at 8:44 AM, Marc Kaufmann  wrote:
> >
> > Let me (ab)use this thread to add some more details on how to submit pull 
> > requests (PR) on GitHub to racket using the GitHub web interface for other 
> > noobs - which includes myself in another month or two. Ideally I would 
> > write this up elsewhere to help with onboarding, but that won't happen 
> > soon, so here we go. We are talking ELI5 (Explain Like I'm 5) level 
> > explanations, so this will be painfully obvious to the vast majority 
> > (although it would be good for someone who knows what they are doing to 
> > correct whatever kludgy workflow I've come up with). I copy most of the 
> > steps from Paulo earlier, but add some that I still had to figure out.
>
> --
> You received this message because you are subscribed to the Google Groups 
> "Racket Users" group.
> To unsubscribe from this group and stop receiving emails from it, send an 
> email to racket-users+unsubscr...@googlegroups.com.
> For more options, visit https://groups.google.com/d/optout.

-- 
You received this message because you are subscribed to the Google Groups 
"Racket Users" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to racket-users+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: [racket-users] How to fix typos in documentation?

[Matthew Butterick]

Perhaps this would be good material for a CONTRIBUTING.md at the top level of 
the repo, where it would be more likely to be found by future contributors. 
GitHub will automatically show a link to the file at arguably appropriate 
times. [1]

[1] https://github.blog/2012-09-17-contributing-guidelines/

> On Mar 8, 2019, at 8:44 AM, Marc Kaufmann  wrote:
> 
> Let me (ab)use this thread to add some more details on how to submit pull 
> requests (PR) on GitHub to racket using the GitHub web interface for other 
> noobs - which includes myself in another month or two. Ideally I would write 
> this up elsewhere to help with onboarding, but that won't happen soon, so 
> here we go. We are talking ELI5 (Explain Like I'm 5) level explanations, so 
> this will be painfully obvious to the vast majority (although it would be 
> good for someone who knows what they are doing to correct whatever kludgy 
> workflow I've come up with). I copy most of the steps from Paulo earlier, but 
> add some that I still had to figure out.

-- 
You received this message because you are subscribed to the Google Groups 
"Racket Users" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to racket-users+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: [racket-users] How to fix typos in documentation?

[Marc Kaufmann]

Let me (ab)use this thread to add some more details on how to submit pull
requests (PR) on GitHub to racket using the GitHub web interface for other
noobs - which includes myself in another month or two. Ideally I would
write this up elsewhere to help with onboarding, but that won't happen
soon, so here we go. We are talking ELI5 (Explain Like I'm 5) level
explanations, so this will be painfully obvious to the vast majority
(although it would be good for someone who knows what they are doing to
correct whatever kludgy workflow I've come up with). I copy most of the
steps from Paulo earlier, but add some that I still had to figure out.

--
Long version (even longer version below. The short version is "Submit a PR;
if you need help, submit an Issue". Obviously.)
--

- go to https://github.com/racket/racket.
- Search for "which is one of the collections with its own testing style"
in the repo
- Go the file with the typo
- Edit it by clicking on the 'Edit' button (pen)
1. If you have already forked the repo, you will be asked to choose
another branch. I chose master. (May be bad.)
2. If you never forked it, it will offer "Fork and edit" and create a
temporary branch patch-1 (or patch-n later on)
- Fix the typo
- Add commit message and comment at the bottom, e.g. "Fix broken link" and
"Fixes #2518" (which fixes issue number 2518 conditional on PR being
accepted)
- Hit 'propose file change', and 'commit changes' on next page
- Later, if accepted, you will be able to choose (somewhere in the
conversation part of the PR) to delete the temporary branch 'patch-n' or
what not. Probably a good idea.
- If you are asked to change part of your PR by the maintainers, go to the
PR page, find the last of your commits, choose 'Edit': "change this file in
the online editor"
- This last part seems kludgy. What's the good workflow?

To add an issue:

- Go to https://github.com/racket/racket.
- Go to issues
- Add new issue, write message and comment, check it's not a duplicate
- If you need to add a permalink to a file where the error is, go to the
file, click on line number, click on the [...] that pops up, 'copy
permalink', add to issue message.
- Submit

--
Even Longer version:
--

I'll use the actual example from yesterday: at
https://docs.racket-lang.org/style/testing.html I found the following " See
the 2htdp ,
which is one of the collections with its own testing style" where the 2htdp
link is broken. Let's fix it.

- The documentation is somewhere on github, so go to
https://github.com/racket/racket.
- Type the following into the search bar, but don't yet hit enter: "which
is one of the collections with its own testing style".
- Github will have a pop-up of two search options, one with "In this
repository" and one with "All of Github". Click "in this repository".
- From the hits you get, open the correct file that contains the typo
(click).
- Fix the typo: Magically you know that the link should point to
https://github.com/racket/htdp/tree/master/htdp-test/2htdp
- (I had to submit an issue to find out, I had searched for it with
'2htdp' and some others, but couldn't figure it out. See below on
submitting issues. Thanks to Sam.)
- Finally, you click the pen button at the top for 'Edit', next to 'Raw',
'Blame', 'History'
- Except it says you need to be signed in
- So you log into GitHub (Or you have to sign up.)
- Now you click 'Edit' (pen button)

Two things can happen:

1. You never forked this repository before for an edit or anything.

- You can click the 'Edit' button (pen) (continue this snoozefest below, at
The Adventure Continues)

2. You already forked this project sometime in the past.

- That was my case. It then says "You must be on a branch to make or
propose changes to this file" when I hover over the pen.
- So you scan to the left side, and up (below the 'racket/racket' and '<>
code') to find something saying what branch you are on. Mine had the poetic
'Tree: 5bb83...'
- Click on the dropdown, choose 'master' (I believe that this is the master
branch of my fork. No clue whether this is stupid in general or not - as
in, I don't know whether my master is in sync automatically with
racket/racket master, as I don't know whether forks remain synched without
me doing anything. It worked this time, so ... )
- Click the pen button, and wait until it loads the branch you chose.

The Adventure Continues:

- Finally, edit: change `@hyperlink["
https://github.com/racket/racket/tree/master/collects/2htdp/"]{2htdp}` to
`@hyperlink["https://github.com/racket/htdp/tree/master/htdp-test/2htdp/;
]{2htdp}`
- At the bottom, type in the commit message and additional comments (where
it says "Propose file change")
- I wrote "Update broken URL" and as additional comments "Fixes #2518".
- The latter part means that I claim that this fixes issue number 2518.
I believe that GitHub automatically understands this and if my pull request

Re: [racket-users] How to fix typos in documentation?

[Marc Kaufmann]

Ergh, of course I forgot to do that part. Thanks for catching that.

On Thu, Mar 7, 2019 at 1:59 PM Paulo Matos  wrote:

>
>
> On 07/03/2019 13:40, Marc Kaufmann wrote:
> > Thanks Paulo, this is way better than the workflow I used the only other
> > time I made a PR. The only thing I had to do was choose a branch to
> > commit to: I chose 'master', mostly because I have no clue what else I
> > would have chosen. What is the default to contribute to?
> >
> > It was in scribblings by the way.
> >
>
> OK, I found you.
> https://github.com/MarcKaufmann/racket/tree/patch-1
>
> As you can see, github created the patch-1 branch correctly and your fix
> is there. You should see now a button in green saying 'Create New Pull
> Request'.
>
> Then it should show something like:
>
> racket/racket master <- MarcKaufmann/racket patch-1
>
> on top. Press create pull request and it will create a pull request in
> racket/racket for master, based on your patch-1 branch changes.
>
> I would then expect to see a PR from you here:
> https://github.com/racket/racket/pulls
>
> --
> Paulo Matos
>

-- 
You received this message because you are subscribed to the Google Groups 
"Racket Users" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to racket-users+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: [racket-users] How to fix typos in documentation?

['Paulo Matos' via Racket Users]

On 07/03/2019 13:40, Marc Kaufmann wrote:
> Thanks Paulo, this is way better than the workflow I used the only other
> time I made a PR. The only thing I had to do was choose a branch to
> commit to: I chose 'master', mostly because I have no clue what else I
> would have chosen. What is the default to contribute to?
> 
> It was in scribblings by the way.
> 

OK, I found you.
https://github.com/MarcKaufmann/racket/tree/patch-1

As you can see, github created the patch-1 branch correctly and your fix
is there. You should see now a button in green saying 'Create New Pull
Request'.

Then it should show something like:

racket/racket master <- MarcKaufmann/racket patch-1

on top. Press create pull request and it will create a pull request in
racket/racket for master, based on your patch-1 branch changes.

I would then expect to see a PR from you here:
https://github.com/racket/racket/pulls

-- 
Paulo Matos

-- 
You received this message because you are subscribed to the Google Groups 
"Racket Users" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to racket-users+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: [racket-users] How to fix typos in documentation?

['Paulo Matos' via Racket Users]

On 07/03/2019 13:40, Marc Kaufmann wrote:
> Thanks Paulo, this is way better than the workflow I used the only other
> time I made a PR. The only thing I had to do was choose a branch to
> commit to: I chose 'master', mostly because I have no clue what else I
> would have chosen. What is the default to contribute to?
> 

In general you should not need to choose a branch to commit to because
github will automatically name it patch-N. Then you create a PR to merge
to master.

If really have to choose a branch to commit your change to in your fork,
select a new branch. I name them - so it could be
mkaufmann-scribblings-typo-fix. Then when you select the branch to merge
to, yes, it's master.

> It was in scribblings by the way.
> 

You mean scribblings in the racket repo?
I am asking because I can't see a PR there from you.

-- 
Paulo Matos

-- 
You received this message because you are subscribed to the Google Groups 
"Racket Users" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to racket-users+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: [racket-users] How to fix typos in documentation?

[Marc Kaufmann]

Thanks Paulo, this is way better than the workflow I used the only other
time I made a PR. The only thing I had to do was choose a branch to commit
to: I chose 'master', mostly because I have no clue what else I would have
chosen. What is the default to contribute to?

It was in scribblings by the way.

Cheers,
Marc

On Thu, Mar 7, 2019 at 12:02 PM 'Paulo Matos' via Racket Users <
racket-users@googlegroups.com> wrote:

>
>
> On 07/03/2019 11:55, Marc Kaufmann wrote:
> > Hi,
> >
> > I just came across a typo in the documentation and was about to move on
> > simply because I couldn't be bothered to figure out how/where to change
> > it. I couldn't find the docs in the github repo (I searched for doc, and
> > looked under racket-lang-org without success).
> >
> > Also, is there a guide on best practice for pull requests or
> > contributions, including a "Fork this, do that, push like that, etc"? I
> > have no idea, usually just fork the whole thing, but don't know how to
> > keep it up-to-date. Pointers to Racket-agnostic resources very welcome.
> > Thanks,
> > Marc
> >
> > PS: I am purposefully not saying where the typo is so that I will have
> > to go and fix it, rather than have someone else fix it.
> >
>
> Where the documentation is, depends on where the typo is. Is it in the
> Guide, Reference, somewhere else?
>
> Go to https://github.com/racket/racket
> then search for the typo in the github search box and select 'in this
> repository'.
>
> Found it, great? No? Maybe the docs are somewhere else. Does it belong
> to one of the libraries in pkgs.racket-lang.org? To scribble?
>
> Once you found it, the easiest thing for a typo is to find the file in
> github, then edit straight in github. It will automatically fork the
> project. Then you can edit the file, fixing the typo and commit. Open PR
> straight after that. Someone will come and merge the PR. :) If you need
> step-by-step help feel free to pvt me in Slack.
>
> Enjoy the ultimate pleasure of committing to the racket repo, go get
> that chocolate bar you deserve!
>
> --
> Paulo Matos
>
> --
> You received this message because you are subscribed to a topic in the
> Google Groups "Racket Users" group.
> To unsubscribe from this topic, visit
> https://groups.google.com/d/topic/racket-users/J8ylMGGGr-8/unsubscribe.
> To unsubscribe from this group and all its topics, send an email to
> racket-users+unsubscr...@googlegroups.com.
> For more options, visit https://groups.google.com/d/optout.
>

-- 
You received this message because you are subscribed to the Google Groups 
"Racket Users" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to racket-users+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: [racket-users] How to fix typos in documentation?

['Paulo Matos' via Racket Users]

On 07/03/2019 11:55, Marc Kaufmann wrote:
> Hi,
> 
> I just came across a typo in the documentation and was about to move on
> simply because I couldn't be bothered to figure out how/where to change
> it. I couldn't find the docs in the github repo (I searched for doc, and
> looked under racket-lang-org without success).
> 
> Also, is there a guide on best practice for pull requests or
> contributions, including a "Fork this, do that, push like that, etc"? I
> have no idea, usually just fork the whole thing, but don't know how to
> keep it up-to-date. Pointers to Racket-agnostic resources very welcome.
> Thanks,
> Marc
> 
> PS: I am purposefully not saying where the typo is so that I will have
> to go and fix it, rather than have someone else fix it.
> 

Where the documentation is, depends on where the typo is. Is it in the
Guide, Reference, somewhere else?

Go to https://github.com/racket/racket
then search for the typo in the github search box and select 'in this
repository'.

Found it, great? No? Maybe the docs are somewhere else. Does it belong
to one of the libraries in pkgs.racket-lang.org? To scribble?

Once you found it, the easiest thing for a typo is to find the file in
github, then edit straight in github. It will automatically fork the
project. Then you can edit the file, fixing the typo and commit. Open PR
straight after that. Someone will come and merge the PR. :) If you need
step-by-step help feel free to pvt me in Slack.

Enjoy the ultimate pleasure of committing to the racket repo, go get
that chocolate bar you deserve!

-- 
Paulo Matos

-- 
You received this message because you are subscribed to the Google Groups 
"Racket Users" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to racket-users+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.