How to fix typos in documentation?

[Marc Kaufmann]

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.

[Paulo Matos]

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

[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

--
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...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[Paulo Matos]

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 <myname>-<feature> 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

[Paulo Matos]

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

[Marc Kaufmann]

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

[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 gets accepted, the issue should automatically be closed.

    - I had opened that issue a little earlier, and that's how I found out from Sam what the correct link/path is.

- Hit "Propose file change"

- On the next page, hit "create pull request"

- Sit back and wait until your PR gets accepted, rejected, or you are asked for amendments.

Now, suppose that one of the maintainers asks you to change something in your PR. After bursting into hysterical laughter (or tears, depending on temperament), you give it a shot:

- Go to the pull requests (https://github.com/racket/racket/pulls) and find your pull request.

- Choose 'commits' at the top

- Click on the commit (there seem to be 5 different ways of doing this)

- It shows the actual patch/diff/change that your early commit did

- Click the pen (Edit) button to "change this file in the online editor"

- This way your earlier changes from the earlier commit (or commits) are there

- Fix whatever needs fixing, add commit message and comment, hit 'commit changes'

- Done (maybe)

Submitting issues:

- So you don't know where the broken link should point to and decide to open an issue.

- Go to racket/racket, click on 'Issues' at the top, click on 'New Issue' (green button on the right at the time of writing)

- Add an issue message, e.g. "Broken link in docs"; Github will tell you that this looks like other issues and ask you to make sure it's not the same. Check it isn't.

- Get the link to the part of the code that needs fixing. For this, I went to the file I knew had to be fixed from the earlier search

- I went to https://github.com/racket/racket/blob/5bb837661c12a9752c6a99f952c0e1b267645b33/pkgs/racket-doc/scribblings/style/testing.scrbl and clicked on the line number 19 since the typo was in line 19.

- This made a [...] field appear on the left of the line. Click on it, choose "Copy permalink".

- Paste this permalink into the comment part of the issue that is still open in another tab. Check via preview that it shows the correct file and line.

- Write something clear and snappy, e.g. "I found this link and it seems broken. I don't know where it should point though."

- Hit submit

Quickly log off your computer before anyone can tell you how to fix the issue yourself! Otherwise, the above at least tells you how you can submit that PR, another Issue, leading to another PR... turtles all the way down.

Cheers,

Marc

PS: This was so utterly painful to write up. If someone knows of tools to record workflows online, that would be really nice. Writing isn't really the right interface to provide this knowledge, but I find videos not that useful either.

[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/

[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.

> --
> 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...@googlegroups.com.

[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 <m...@mbtype.com> wrote:

--
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...@googlegroups.com.

[David Storrs]

On Fri, Mar 8, 2019 at 3:13 PM Greg Hendershott <greghen...@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?

[Ben Greenman]

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.

[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

--
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...@googlegroups.com.

[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