[Vm-dev] git mavens, shortcut please?

[Ben Coman]

On Sun, Jun 19, 2016 at 8:41 AM, tim Rowledge <tim at rowledge.org> wrote:
>
> Actually, calling all git mavens - please, please, point the rest of us to some documentation that might possibly be understood by humans. Some of us have no idea at all how this works

I found these Atlassian tutorials really nice (and often refer to them)...
* https://www.atlassian.com/git/tutorials

Github Help "Fork a repo"  provides a scratch repo for you to practice
on without fear.
* https://help.github.com/

git - the simple guide (I only just bumped into this, looks good)
* http://rogerdudler.github.io/git-guide/

> and need something in style of ‘see spot download some code. See spot build it. Run it, spot, run it! Oh dear, spot - a bug. Fix the bug, spot, fix it! Now save the code. Now pour the custard in m’boots!' and so on.

Okay Spot.  Here is a proposed recipe. This is for those having having
write access to the official repository and cloned that to work in.
I'll follow up with an adaption for forked repos tomorrow.

1. Go to https://github.com/OpenSmalltalk/vm

2.  Click the green <Clone or download> button.
     (If you've already set up your SSH keys, click "Use SSH".)
     then copy the url to the clipboard.

3. Clone to your local machine
    $ git clone #paste url from the clipboard here
    $ cd vm
    $ git remove -v
origin git at github.com:OpenSmalltalk/vm.git (fetch)
origin git at github.com:OpenSmalltalk/vm.git (push)
or...
origin https://github.com/OpenSmalltalk/vm.git (fetch)
origin https://github.com/OpenSmalltalk/vm.git (push)
...depending on ssh or https clone respectively

4. Create a branch to work on...
    $ git fetch    #updates all branches to latest
    $ git checkout -b SomeBug Cog

5. Edit, compile, test cycle.  Commit often along the way.
    * make required changes
    $ git stage -u
    $ git diff ; git diff HEAD
    $ git commit -m "SomeBug - part way there"
Repeat as necessary

6. Ready to submit.  Clean up *local* history (since we committed quite often)
    $ git rebase -i    # Squash inconsequential commits. Rebase is
okay before publishing.
    Ref: https://www.atlassian.com/git/articles/git-team-workflows-merge-or-rebase/
            https://www.atlassian.com/git/tutorials/merging-vs-rebasing/conceptual-overview

7. Catch up to official Cog branch
    $ git fetch     # updates origin/*
    $ git log HEAD..origin/Cog    # review other updates
    $ git diff origin/Cog   # review other updates
Depending on whether the final history should be linear (more like SVN??)
    $ git rebase origin/Cog   # rebase okay since not yet published
or show the branching...
   $ get merge origin/Cog
...might depend on whether its a small fix or a larger feature added.

8. Submit for review
    $ git push    # to server
You will see...
           fatal: The current branch SomeBug has no upstream branch.
which is because the SomeBug branch only exists locally, not on the
github server. The following creates the branch on the "origin" server
and sets things so subsequently this branch only requires "git push".
    $ git push --set-upstream origin SomeBug
    * On github, from the <Branch> pulldown button, select your SomeBug branch.
    * Click <New pull request> button.  For more detail refer...
       https://help.github.com/articles/using-pull-requests/

(In the meantime, work on some other branch)

7. Reviewers can download PR to test locally as described here...
https://help.github.com/articles/checking-out-pull-requests-locally/
(though I've not done that since I've not been on the receiving side
of a pull request before)

8. Respond to reviewer comments. Edit, compile, test, resubmit.
    $ git checkout SomeBug
    * make required changes
    $ git stage -u
    $ git commit -m "changed per feedback "
    $ git push    # Pull request auto updated
(Repeat as required)

9. Pull request acceptable.  Optionally (and some policy discussion
required) squash changes from review period.
   $ git rebase -i
   $ git push -f
Note this does rewrite the history of the published SomeBug branch,
but presumably the branch is thrown away after integration so no real
foul.  But forcing pushing may be risk for accidentally doing it to
the Cog or master branches.  (btw, has the force protection on those
two branches been tested?)

10. On github, integrator accepts pull request.

11. Delete branch.