Merge pull request #298 from coderefinery/radovan/concepts

Updated the "concepts" episode

Author: bast

content/concepts.md

@@ -1,22 +1,8 @@
 # Concepts around collaboration
 
-```{objectives}
+:::{objectives}
 - Be able to decide whether to divide work at the branch level or at the repository level.
-```
-
-```{instructor-note}
-- 15 min teaching
-```
-
-
-## Motivation
-
-- Someone has given you access to a repository online and you want to contribute?
-- We will learn how to make a copy and send changes back.
-- Then, we make a "pull request" that allows a review.
-- Once we know how code review works, we will be able to propose changes
-  to repositories of others and review changes submitted by external
-  contributors.
+:::
 
 
 ## Commits, branches, repositories, forks, clones
@@ -33,84 +19,80 @@
 
 ## 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/clone.png
-:alt: Cloning
+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
 
-Cloning
-```
+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.
+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.
 
-```{figure} img/overview/fork.png
-:alt: Forking
-:width: 100%
-:class: with-border
 
-Forking
-```
+## 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.
 
-## Generating from templates and importing
 
-There are two more ways to create "copies" of repositories into your user space:
-- A repository can be marked as **template** and new repositories can be
-  **generated** from it, like using a cookie-cutter.
-  The newly created repository will start with a new history, only one commit, and not
-  inherit the history of the template.
+## Should we clone or fork?
 
-```{figure} img/overview/generate.png
-:alt: Generating from a template
-:width: 100%
-:class: with-border
+Should we all work on forks or should we all work inside one repository?
 
-Generating from a template.
-```
+- For most small or medium-sized research projects you probably want to **work by
+  cloning a repository** that all research group has write access to (we will
+  exercise this in the next section).
 
-- You can **import** a repository from another hosting service or web address.
-  This will preserve the history of the imported project.
+- It's only when you want to contribute to a project that you don't have write
+  access to that you need to use **forks** (we will practice this as well).
 
-```{figure} img/overview/import.png
-:alt: Importing a repository
-:width: 100%
-:class: with-border
 
-Importing a repository.
-```
----
+## Generating from templates
 
-```{discussion}
-- Visit one of the repositories/projects that you have used recently and try to find out
-  how many forks exist and where they are.
-- In which situations could it be useful to start from a "template" repository by generating?
-```
+A repository can be marked as **template** and new repositories can be
+**generated** from it, like using a cookie-cutter.
 
+The newly created repository will start with a new ("flattened") history, only one commit, and not
+inherit the history of the template.
 
-## 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.
-
-```{figure} img/overview/forkandclone.png
-:alt: Forking and cloning
+:::{figure} img/overview/generate.png
+:alt: Generating from a template
 :width: 100%
 :class: with-border
 
-Forking and cloning
-```
+Generating from a template.
+:::