help and screenshots for "Collaborating within the same repository"

content/same-repository.md

@@ -117,6 +117,151 @@ most research groups.
 :::
 
 
-## Solution and walk-through
+## Help and discussion
 
-We will add this before the lesson.
+
+### Pushing local changes to the remote repository
+
+This is only necessary if you created the changes locally. If you created the
+changes directly on GitHub, you can skip this step.
+
+:::::{tabs}
+::::{group-tab} VS Code
+In VS Code, you can "publish the branch" to the remote repository by clicking
+the cloud icon in the bottom left corner of the window:
+:::{figure} img/same-repository/vscode-publish-branch.png
+:width: 60%
+:class: with-border
+:alt: Publishing a branch in VS Code
+:::
+::::
+
+::::{group-tab} Command line
+If you have a local branch `my-branch` and you want to push it to the remote
+and make it visible there, first verify what your remote is:
+```console
+$ git remote --verbose
+
+origin	[email protected]:user/centralized-workflow-exercise.git (fetch)
+origin	[email protected]:user/centralized-workflow-exercise.git (push)
+```
+
+In this case the remote is called `origin` and refers to the address
+[email protected]:user/centralized-workflow-exercise.git.  Both can be used
+interchangeably. Make sure it points to the right repository, ideally a
+repository that you can write to.
+
+Now that you have a remote, you can push your branch to it:
+```console
+$ git push origin my-branch
+```
+This will create a new branch on the remote repository with the same name as
+your local branch.
+
+You can also do this:
+```console
+$ git push --set-upstream origin my-branch
+```
+This will connect the local branch and the remote branch so that in the future
+you can just type `git push` and `git pull` without specifying the branch name
+(but this depends on your Git configuration).
+
+
+**Troubleshooting**
+
+If you don't have a remote yet, you can add it with (adjust `ADDRESS` to your repository address):
+```console
+$ git remote add origin ADDRESS
+```
+
+ADDRESS is the part that you copy from here:
+:::{figure} img/same-repository/clone-address.png
+:width: 60%
+:class: with-border
+:alt: Copying the clone address from GitHub
+::::
+
+If the remote points to the wrong place, you can change it with:
+```console
+$ git remote set-url origin NEWADDRESS
+```
+::::
+:::::
+
+
+### What is a protected branch? And how to modify it?
+
+A protected branch on GitHub or GitLab is a branch that cannot (accidentally)
+deleted or force-pushed to. It is also possible to require that a branch cannot
+be directly pushed to or modified, but that changes must be submitted via a
+pull request.
+
+To protect a branch in your own repository, go to "Settings" -> "Branches".
+
+
+### Cross-referencing issues and pull requests
+
+Each issue and each pull request gets a number and you can cross-reference them.
+
+When you open an issue, note down the issue number (in this case it is `#2`):
+:::{figure} img/same-repository/issue-number.png
+:width: 60%
+:class: with-border
+:alt: Each issue gets a number
+:::
+
+You can reference this issue number in a commit message or in a pull request, like in this
+commit message:
+```text
+this is the new recipe; fixes #2
+```
+
+If you forget to do that in your commit message, you can also reference the issue
+in the pull request description. And instead of `fixes` you can also use `closes` or `resolves`
+or `fix` or `close` or `resolve` (case insensitive).
+
+Here are all the keywords that GitHub recognizes:
+<https://help.github.com/en/articles/closing-issues-using-keywords>
+
+Then observe what happens in the issue once your commit gets merged: it will
+automatically close the issue and create a link between the issue and the
+commit. This is very useful for tracking what changes were made in response to
+which issue and to know from when until when precisely the issue was open.
+
+
+### Reviewing pull requests
+
+Checklist for reviewing a pull request:
+- Be kind, on the other side is a human who has effort into this.
+- Be constructive: if you see a problem, suggest a solution.
+- Towards which branch is this directed?
+- Is the title descriptive?
+- Is the description informative?
+- Scroll down to see commits.
+- Scroll down to see the changes.
+- Again, be kind and constructive.
+- Later we will learn how to suggest changes directly in the pull request.
+
+
+### Draft pull requests
+
+Try to create a draft pull request:
+:::{figure} img/same-repository/draft-pr.png
+:width: 60%
+:class: with-border
+:alt: Creating a draft pull request
+::::
+
+Verify that the draft pull request cannot be merged until it is marked as ready
+for review:
+:::{figure} img/same-repository/draft-pr-wip.png
+:width: 60%
+:class: with-border
+:alt: Draft pull request cannot be merged
+::::
+
+Draft pull requests can be useful for:
+- **Feedback**: You can open a pull request early to get feedback on your work without
+  signaling that it is ready to merge.
+- **Information**: They can help communicating to others that a change is coming up and in
+  progress.