deploy: c293bcc

_sources/collaboration.md.txt

@@ -0,0 +1,13 @@
+(collaboration)=
+
+# Collaborative version control and code review
+
+```{toctree}
+:maxdepth: 1
+
+collaboration/concepts.md
+collaboration/same-repository.md
+collaboration/code-review.md
+collaboration/forking-workflow.md
+collaboration/demo-discussion.md
+```

_sources/collaboration/code-review.md.txt

@@ -0,0 +1,144 @@
+(code-review)=
+
+# Practicing code review
+
+In this episode we will practice the code review process. We will learn how to
+ask for changes in a pull request, how to suggest a change in a pull request,
+and how to modify a pull request.
+
+This will enable research groups to work more collaboratively and to not only
+improve the code quality but also to learn from each other.
+
+
+## Exercise
+
+:::{prereq} Exercise preparation
+We can continue in the same exercise repository which we have used in the
+previous episode.
+:::
+
+:::{exercise} Exercise: Practicing code review (25 min)
+
+**Technical requirements**:
+- If you create the commits locally: [Being able to authenticate to GitHub](https://coderefinery.github.io/installation/ssh/)
+
+**What is familiar** from previous lessons:
+- Creating a branch.
+- Committing a change on the new branch.
+- Opening and merging pull requests.
+
+**What will be new** in this exercise:
+- As a reviewer, we will learn how to ask for changes in a pull request.
+- As a reviewer, we will learn how to suggest a change in a pull request.
+- As a submitter, we will learn how to modify a pull request without closing
+  the incomplete one and opening a new one.
+
+**Exercise tasks**:
+1. Create a new branch and one or few commits: in these improve something but also
+   deliberately introduce a typo and also a larger mistake which we will want to fix during the code review.
+1. Open a pull request towards the main branch.
+1. As a reviewer to somebody else's pull request, ask for an improvement and
+   also directly suggest a change for the small typo. (Hint:
+   suggestions are possible through the GitHub web interface, view of
+   a pull request, "Files changed" view, after selecting some lines.
+   Look for the "±" button.)
+1. As the submitter, learn how to accept the suggested change.  (Hint:
+   GitHub web interface, "Files Changed" view.)
+1. As the submitter, improve the pull request without having to close and open
+   a new one: by adding a new commit to the same branch. (Hint: push
+   to the branch again.)
+1. Once the changes are addressed, merge the pull request.
+:::
+
+
+## Help and discussion
+
+From here on out, we don't give detailed steps to the solution.  You
+need to combine what you know, and the extra info below, in order to
+solve the above.
+
+### How to ask for changes in a pull request
+
+Technically, there are at least two common ways to ask for changes in a pull
+request.
+
+Either in the comment field of the pull request:
+:::{figure} img/code-review/comment.png
+:width: 60%
+:class: with-border
+:alt: Screenshot of a pull request comment field
+::::
+
+Or by using the "Review changes":
+:::{figure} img/code-review/files-changed.png
+:width: 100%
+:class: with-border
+:alt: Screenshot of a pull request navigating to the "Review changes" tab
+::::
+
+And always please be kind and constructive in your comments. Remember that the
+goal is not gate-keeping but **collaborative learning**.
+
+
+### How to suggest a change in a pull request as a reviewer
+
+If you see a very small problem that is easy to fix, you can suggest a change
+as a reviewer.
+
+Instead of asking the submitter to tiny problem, you can suggest a change by
+clicking on the plus sign next to the line number in the "Files changed" tab:
+:::{figure} img/code-review/leave-comment.png
+:width: 100%
+:class: with-border
+:alt: Screenshot of leaving a comment to a line in a pull request
+::::
+
+Here you can comment on specific lines or even line ranges.
+
+But now the interesting part is to click on the "Add a suggestion" symbol (the
+one that looks like plus and minus). Now you can fix the tiny problem (in this
+case a typo) and then click on the "Add single comment" button:
+:::{figure} img/code-review/add-suggestion.png
+:width: 60%
+:class: with-border
+:alt: Sequence of clicks to add a suggestion to a line in a pull request
+::::
+
+The result is this and the submitter can accept the change with a single click:
+:::{figure} img/code-review/commit-suggestion.png
+:width: 60%
+:class: with-border
+:alt: Screenshot of a pull request with a suggested change
+::::
+
+After accepting with "Commit suggestion", the improvement gets added to the
+pull request.
+
+
+### How to modify a pull request to address the review comments
+
+If the reviewer asks for changes, it is not necessary to close the pull request
+and later open a new one. It can even be counter-productive to do so: This can
+fragment the discussion and the history of the pull request and can make it
+harder to understand the context of the changes.
+
+A much better mechanism to recognize that pull requests are not implemented
+from a specific commit to a specific branch, but **always from a branch to a
+branch**.
+
+This means that you can make amendments to the pull request by adding new
+commits to the same source branch. This way the pull request will be updated
+automatically and the reviewer can see the new changes and comment on them.
+
+The fact that pull requests are from branch to branch also strongly suggests
+that it is a good practice to create a new branch for each pull request.
+Otherwise you could accidentally modify an open pull request by adding new
+commits to the source branch.
+
+
+## Summary
+
+- Our process isn't just about code now.  It's about discussion and
+  working together to make the whole process better.
+- GitHub discussions and reviewing are quite powerful and can make
+  small changes easy.

_sources/collaboration/concepts.md.txt

@@ -0,0 +1,69 @@
+(concepts)=
+
+# Concepts around collaboration
+
+```{objectives}
+- Be able to decide whether to divide work at the branch level or at the repository level.
+```
+
+
+## Commits, branches, repositories, forks, clones
+
+- **repository**: The project, contains all data and history (commits, branches, tags).
+- **commit**: Snapshot of the project, gets a unique identifier (e.g. `c7f0e8bfc718be04525847fc7ac237f470add76e`).
+- **branch**: Independent development line. The main development line is often called `main`.
+- **tag**: A pointer to one commit, to be able to refer to it later. Like a [commemorative plaque](https://en.wikipedia.org/wiki/Commemorative_plaque)
+  that you attach to a particular commit (e.g. `phd-printed` or `paper-submitted`).
+- **cloning**: Copying the whole repository to your laptop - the first time. It is not necessary to download each file one by one.
+- **forking**: Taking a copy of a repository (which is typically not yours) - your
+  copy (fork) stays on GitHub/GitLab and you can make changes to your copy.
+
+
+## Cloning a repository
+
+In order to make a complete copy a whole repository, the `git clone` command
+can be used. When cloning, all the files, of all or selected branches, of a
+repository are copied in one operation. Cloning of a repository is of relevance
+in a few different situations:
+* Working on your own, cloning is the operation that you can use to create
+  multiple instances of a repository on, for instance, a personal computer, a
+  server, and a supercomputer.
+* The parent repository could be a repository that you or your colleague own. A
+  common use case for cloning is when working together within a smaller team
+  where everyone has read and write access to the same git repository.
+* Alternatively, cloning can be made from a public repository of a code that
+  you would like to use. Perhaps you have no intention to work on the code, but
+  would like to stay in tune with the latest developments, also in-between
+  releases of new versions of the code.
+
+
+```{figure} img/overview/forkandclone.png
+:alt: Forking and cloning
+:width: 100%
+:class: with-border
+
+Forking and cloning
+```
+
+
+## Forking a repository
+
+When a fork is made on GitHub/GitLab a complete copy, of all or selected
+branches, of the repository is made. The copy will reside under a different
+account on GitHub/GitLab. Forking of a repository is of high relevance when
+working with a git repository to which you do not have write access.
+* In the fork repository commits can be made to the base branch (`main` or
+  `master`), and to other branches.
+* The commits that are made within the branches of the fork repository can be
+  contributed back to the parent repository by means of pull or merge requests.
+
+
+## Synchronizing changes between repositories
+
+- We need a mechanism to communicate changes between the repositories.
+- We will **pull** or **fetch** updates **from** remote repositories (we will soon discuss the difference between pull and fetch).
+- We will **push** updates **to** remote repositories.
+- We will learn how to suggest changes within repositories on GitHub and across repositories (**pull request**).
+- Repositories that are forked or cloned do not automatically synchronize themselves:
+  We will learn how to update forks (by pulling from the "central" repository).
+- A main difference between cloning a repository and forking a repository is that the former is a general operation for generating copies of a repository to different computers, whereas forking is a particular operation implemented on GitHub/GitLab.

_sources/collaboration/demo-discussion.md.txt

@@ -0,0 +1,5 @@
+(collaboration-demo-discussion)=
+
+# Conclict resolution, rebasing, and organizational strategies
+
+(40 min demo and discussion)