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 <https://github.com/racket/racket/tree/master/collects/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. On Thu, Mar 7, 2019 at 2:05 PM Marc Kaufmann <marc.kaufman...@gmail.com> wrote: > Ergh, of course I forgot to do that part. Thanks for catching that. > > On Thu, Mar 7, 2019 at 1:59 PM Paulo Matos <pmatos@linki.tools> 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.
