Move 3-github to pycalc

Author: jni

3-github.md

@@ -40,8 +40,8 @@ flag:
 
 ```console
 $ git remote -v
-origin	[email protected]:jni/r-string-calc (fetch)
-origin	[email protected]:jni/r-string-calc (push)
+origin	[email protected]:jni/pycalc (fetch)
+origin	[email protected]:jni/pycalc (push)
 ```
 
 That tells both the name of the remote, *and its location*. "origin" is
@@ -60,25 +60,48 @@ Delta compression using up to 4 threads.
 Compressing objects: 100% (36/36), done.
 Writing objects: 100% (36/36), 3.33 KiB | 0 bytes/s, done.
 Total 36 (delta 25), reused 0 (delta 0)
-To [email protected]:jni/r-string-calc
+To [email protected]:jni/pycalc
    8ab0457..8de6fb7  master -> master
 ```
 
 Read the above as "push to "origin" my branch "master" onto its branch
-"master".
+"master". Branches are managed locally for each repository, so the branch names
+don't actually have to match. That is, we could easily have written:
 
-After this, you'll be able to refresh your repo page on GitHub and
+```console
+$ git push origin master:other-branch-name
+```
+
+and then the contents of our branch `master` locally would be mirrored in the
+remote branch `other-branch-name` on `origin`. In order to tell git to keep
+track of matching branch names, use the option `--set-upstream`:
+
+```console
+$ git push origin --set-upstream master
+```
+
+This tells git: "push `master` onto `origin`'s `master`, and note that they are
+mirrors of each other." This means that later, we only need to do:
+
+```console
+$ git push origin
+```
+
+And git will know that `master` goes onto `origin`'s `master`.
+
+After this, you'll be able to refresh your page on GitHub and
 browse your code's history.
 
 ## Exercise 4: GitHub pull requests
 
 For this exercise you will have to pair up with your neighbour, which
 we will name Alice. (And your name is Bob, in keeping with the computer
-science literature.)
+science literature.) Decide now who will be Bob and who will be Alice in the
+pair.
 
-Delete your "r-string-calc" repository on GitHub (this is done under "Settings"
-in the right-hand menu). You've realised that Alice has her own version and
-that you can both save effort by collaborating on this project.
+As Bob, you should delete your "pycalc" repository on GitHub (this is done
+under "Settings" in the right-hand menu). You've realised that Alice has her
+own version and that you can both save effort by collaborating on this project.
 
 You've been wanting to do some arithmetic on some data, but the first
 number you need to add is often a decimal number. In those cases, the
@@ -88,39 +111,41 @@ You want to modify it so that the first number is allowed to be a decimal
 number.
 
 Navigate to Alice's repository on GitHub
-(https://github.com/[Alice's username]/r-string-calc), and click the "Fork"
+(https://github.com/[Alice's username]/pycalc), and click the "Fork"
 button.
 This will create a copy of Alice's repo on your GitHub account, which
 you can then clone on your machine as before. But note that you need to
-delete your existing repository! Instructions below (some of the directories
-and obviously the "bob" username needs to be changed to yours!):
+delete your existing work, or git will complain! Instructions below (some of
+the directories and obviously the "bob" username needs to be changed to
+yours!):
 
 ```console
 $ pwd
-/Users/bob/projects/r-string-calc
+/Users/bob/projects/pycalc
 $ cd ..
-$ rm -rf r-string-calc
-$ git clone [email protected]:bob/r-string-calc.git
-$ cd r-string-calc
-$ git checkout -b decimals
+$ rm -rf pycalc
+$ git clone [email protected]:alice/pycalc
+$ cd pycalc
+$ git switch --create decimals
 ```
 
-Edit the `strcalc.R` file so that `num0` is converted with `as.numeric`
-instead of `as.integer`.
+Edit the `calc.py` file so that `num0` is converted with `float`
+instead of `int`. (Leave `num1` unchanged for now.)
 
 Now commit those changes and push them *to a new branch on GitHub*. If you use
 the `--set-upstream` flag, you tell git to create a branch with the same
 name that "tracks" the current branch. This makes future pushes easier.
 
 ```console
-$ git add strcalc.R
+$ git add calc.py
 $ git commit -m "Allow num0 to be any decimal number"
 $ git push origin --set-upstream decimals
 ```
 
 Go to the GitHub page for the project. You should see a new button
 showing that you've recently updated a branch and prompting you to
-*initiate a pull request*.
+*initiate a pull request*. (You can also copy the "new pull request" address
+from git's message when you push.)
 
 Here's how this works: you don't know Alice. You probably have never met
 her. So it's natural that you can't just push random stuff willy-nilly to her
@@ -131,7 +156,7 @@ changes, you ask *her* to *pull* from your own history.
 The PR will tell Alice that you've made some
 changes to the code and you would like her to incorporate them into
 her project. Notice that you did this *without needing any special
-access from Alice!* This is the magic of GitHub.
+access from Alice!* This is the magic of GitHub and open source.
 
 Check out the impact that GitHub has had on a few open source Python projects:
 
@@ -153,30 +178,28 @@ title and message here is very important!
 > When in Rome, do as the Romans do. Look at their existing codebase
 > and try to follow their example. (This is not to say that you can't
 > improve on it; but make sure your documentation and testing *at least*
-> least meets their standards.)
-
+> meets their standards.
 
 
 Alice should get an email notification that there is a pull request to
 her project. Clicking on it, she will be taken to the web form for the
-PR, where she can examine the changes that Bob has made (the "Files changed"
-tab).
+PR, where she can examine the changes that Bob has made (the "Files" tab).
 
 Alice will note that this great change would be made much more useful if it
-also used `as.numeric` for `num1`! She comments on the
+also used `float` for `num1`! She comments on the
 PR page: "This is a great addition, thanks! Could you please do the same for
 num1?"
 
 On his machine, Bob makes the requested change, commits, and pushes his changes:
 
 ```console
-$ #  ... edit strcalc.R ...
-$ git add strcalc.R
-$ git commit -m "Use as.numeric for num1's conversion also"
+$ #  ... edit calc.py ...
+$ git add calc.py
+$ git commit -m "Use float for num1's conversion also"
 $ git push  # no need to specify repo or branch anymore, having `set-upstream`
 ```
 
-If both Bob and Alice go back to the PR page, they will see that the PR has
+If either Bob or Alice go back to the PR page, they will see that the PR has
 been automagically updated with Bob's new changes! (Though they may need to
 refresh the page.)
 
@@ -194,28 +217,29 @@ For this, he needs to add it to his list of remotes (remember remotes?):
 
 ```console
 $ git remote -v
-origin	[email protected]:bob/r-string-calc (fetch)
-origin	[email protected]:bob/r-string-calc (push)
-$ git remote add upstream [email protected]:alice/r-string-calc
+origin	[email protected]:bob/pycalc (fetch)
+origin	[email protected]:bob/pycalc (push)
+$ git remote add upstream [email protected]:alice/pycalc
 $ git remote -v
-origin	[email protected]:bob/r-string-calc (fetch)
-origin	[email protected]:bob/r-string-calc (push)
-upstream	[email protected]:alice/r-string-calc (fetch)
-upstream	[email protected]:alice/r-string-calc (push)
-$ git checkout master
+origin	[email protected]:bob/pycalc (fetch)
+origin	[email protected]:bob/pycalc (push)
+upstream	[email protected]:alice/pycalc (fetch)
+upstream	[email protected]:alice/pycalc (push)
+$ git switch master
 $ git pull upstream master  # get upstream's master branch, and merge
+$ git push origin master
 ```
 
 Bob can now inspect his history log and see that both his changes and Alice's
-merge are there. Use GitX for this or the `lsd` alias we learned earlier, or
-a simple git-log will also do.
+merge are there. Use GitKraken/GitX/GitTower/other GUI for this, or the `lsd`
+alias we learned earlier, or a simple git-log will also do.
 
 ## Bonus exercise 1: self-PRs and code review
 
 Do the reverse approach, which is a bit different. Alice has gained a
 collaborator in Bob. Even though she still maintains control of the project
-repository, she wants to enlist his help. She sprouts a branch, adds a line or
-two (for example, she might want to add a test function, `test.compute`, that
+repository, she wants to enlist his help. She creates a branch, adds a line or
+two (for example, she might want to add a test function, `test_compute`, that
 runs `compute` for a few known values and makes sure the results match up), then
 *creates a PR against her own repository.* She then asks Bob to review her
 change by mentioning his username (e.g. `@bob`, as in Twitter) in a comment on
@@ -243,7 +267,7 @@ The common solution is to *rebase*, that is, to replay the changes on Bob's
 branch on top of the latest `master` from Alice's repository.
 
 ```console
-$ git checkout master
+$ git switch master
 $ git pull upstream master
 $ git rebase master test-2
 ```