Some hints on using GitHub for the PNG specification. Part one, your first pull request

I have noticed some common issues with pull requests, and thought these 
notes might be helpful.
In particular if you see that your edit includes, like, every other edit 
you made previously, then these notes might well help.


    Getting started

I'm going to assume that you have either forked the repository and 
cloned it locally, or just cloned the repo locally. The latter is easier 
so these notes will focus on that.

git clone git@github.com:w3c/PNG-spec.git

This makes a new directory PNG-spec and clones the GitHub repository 
into it. You will be on the *main *branch.


    Making an edit

If you want to make a change to the spec the first thing you need to do 
is make sure your local copy is up to date.

cd PNG-spec
git pull --rebase

This will update your local copy and then replay and changes you have 
made, on top of that.

Now you need to make a new branch to contain your edits. Suppose we are 
going to change all textual instances of "colour" to US-English "color". 
We give our branch a name:

git checkout -b colour-to-color

Git will confirm what you just did:

Switched to a new branch 'colour-to-color'

Now you make your changes (this will be to index.html, in general), 
save, and git commit them. Normally I commit from within my editor 
(Microsoft VS Code) but here I will do it from the command line as well. 
We use a human-readable message and, if the change relates to a GitHub 
issue, we provide the issue number as well:

git add index.html
git commit -m "Use US-English color in visible text, preserving incoming 
links that use colour #374"

Git gives us some feedback to confirm what we did:

[colour-to-color a2ce52b] Use US-English color in visible text, 
preserving incoming links that use colour #374
  1 file changed, 230 insertions(+), 230 deletions(-)

Now we want to push our local change to the main GitHub repository. The 
syntax is complicated and I always forget. Luckily git will remind me 
what to do and I can just copy and paste that.

git push

Git tells you off, but also says what you should have done. No worries, 
nothing is broken!

fatal: The current branch colour-to-color has no upstream branch.
To push the current branch and set the remote as upstream, use

     git push --set-upstream origin colour-to-color

OK, so we copy and paste that.

git push --set-upstream origin colour-to-color

Git is happy, confirms what we did, and even tells us what to do next:

Enumerating objects: 12, done.
Counting objects: 100% (12/12), done.
Delta compression using up to 20 threads
Compressing objects: 100% (9/9), done.
Writing objects: 100% (9/9), 3.39 KiB | 20.00 KiB/s, done.
Total 9 (delta 6), reused 0 (delta 0)
remote: Resolving deltas: 100% (6/6), completed with 3 local objects.
remote:
remote: Create a pull request for 'colour-to-color' on GitHub by visiting:
remote: https://github.com/w3c/PNG-spec/pull/new/colour-to-color
remote:
To github.com:w3c/PNG-spec.git
  * [new branch]      colour-to-color -> colour-to-color
Branch 'colour-to-color' set up to track remote branch 'colour-to-color' 
from 'origin'.

So we paste https://github.com/w3c/PNG-spec/pull/new/colour-to-color 
into a browser and it makes a new pull request for us. Press the green 
"Create pull request" button and off we go.

Stay tuned for thrilling part two, what happens when people request changes.

-- 
Chris Lilley
@svgeesus
Technical Director @ W3C
W3C Strategy Team, Core Web Design
W3C Architecture & Technology Team, Core Web & Media