Merge pull request #138 from esciencecenter-digital-skills/vc-module-…

…dbodor

VC module

modules/version-control/slides-version-control.md

@@ -62,7 +62,7 @@ The changes are stored along with some useful metadata. A set of changes, along
 ## More than one...
 
 <div style="float: left; width: 49%;">
-  independent changes
+  independent change
   <img style="height: 350px;" src="media/versions.svg"/>
 </div>
 
@@ -72,9 +72,58 @@ The changes are stored along with some useful metadata. A set of changes, along
 </div>
 
 note:
-When collaborating you might have various versions (sets of changes) that co-exist at the same time on so called "branches".
+When collaborating you might have various versions (sets of changes) that co-exist at the same time on so called "branches". Modern version control software can usually automatically merge multiple changes into a single document.
 
-As long as the changes are not made to the same section (line of text) in a document (**conflict!**), the various changes can be merged together. 
+===
+
+<!-- .slide: data-state="standard" -->
+## Merge conflicts
+
+However, if multiple contributors work on the same thing...
+
+```bash
+This line contains a typos.
+```
+<!-- .element: class="fragment" data-fragment-index="1" -->
+
+... then "merge conflicts" may arise: 
+<!-- .element: class="fragment" data-fragment-index="2" -->
+
+```bash
+<<<<<<< contributor1
+This line contains typos.
+=======
+This line contains a typo.
+>>>>>>> contributor2
+```
+<!-- .element: class="fragment" data-fragment-index="2" -->
+
+note:
+
+If changes are made to the same section (usually the same or consecutive line(s) of text) of a document a **conflict** arises. Changes cannot be automatically merged, as the interpreter does not know which version or which combination to use. Human intervention is required and can involve rolling back a change, finding common ground between changes, etc.
+
+===
+
+<!-- .slide: data-state="standard center" -->
+## Avoiding merge conflicts
+
+How to minimize creating merge conflicts:
+
+- Communicate:
+  - discuss who is working on what
+  - agree on common standards such as formatting, (conflicting) style guides, linting rules, etc.
+- Frequent merging:
+  - Merge (small) changes back to the central repository often
+  - Pull changes to your local repository regularly
+- Organize changes:
+  - use "feature branches" rather than making changes to the main document directly 
+  - avoid "scope creep" and instead create separate independent branches for isolated topics
+  - review each other's changes before merging them
+
+<!-- .element: class="fragment" data-fragment-index="1" -->
+
+note:
+Resolving merge conflicts can be time-consuming and error prone, especially for larger changes/conflicts. Therefore it is a good idea for teams to agree on some basic practices to avoid creating conflicts in the first place. Keep in mind, that it is unrealistic to prevent all conflicts. This is fine, but they will need some attention to resolve. 
 
 ===
 
@@ -97,8 +146,8 @@ Collaborative code developers often make use of a remote server (like GitHub, or
 Files can be stored in:
  - **working directory**: the files you can see
  - **staging area / index**: files about to be committed
- - **local repository**: the permanent record
- - **remote repository**: a copy of the repository which is stored online and often acts as the central repository
+ - **local repository**: the (permanent) record on a given user's disk 
+ - **remote repository**: an online copy of the record, often used as the central repository
 
 ===
 
@@ -120,4 +169,4 @@ Git (for version control) with Gitlab and Github (for collaboration) are the mai
 - Version control is like unlimited **undo** in MS Word, and more
 - Version control also allows many people to work in parallel
 - For collaborative development a remote, cloud hosted repository is often used as central hub
-
+- Communication is key to avoid conflicting versions of the same software

modules/version-control/version_control_exercise.md

@@ -0,0 +1,17 @@
+---
+title: What to include in the repository
+type: exercise
+order: 3
+---
+
+## Exercise: Which of the following do you think should be part of a code repository (5-10 mins)
+
+Discuss with your neighbor which of the following should be part of the code repository and why it should or should not.
+
+Discuss with your neighbor which of the following should be part of the code repository and why it should or should not.
+
+- installation instructions (i.e. detailed instructions on how to install the software)
+- user documentation (i.e. information for the users of the software about its functionality and features)
+- full dataset to reproduce figures from a paper
+- a few data files to test the functionality of the code base
+- in-line comments intended only for code developers

modules/version-control/version_control_resources.md

@@ -8,6 +8,8 @@ order: 5
 
 [Version Control with Git: Automated Version Control (swcarpentry.github.io)](https://swcarpentry.github.io/git-novice/01-basics.html) 
 
+[Git commands cheat sheet](https://training.github.com/downloads/github-git-cheat-sheet.pdf)
+
 https://the-turing-way.netlify.app/reproducible-research/vcs 
 
 https://coderefinery.github.io/git-intro/

modules/version-control/version_control_terminology.md

@@ -11,4 +11,6 @@ order: 2
 * **Pull/push**: Copy revisions/commits from one repository into another. Pull is initiated by the receiving repository, while push is initiated by the source. Fetch is sometimes used as a synonym for pull, or to mean a pull followed by an update. 
 * **Pull/merge request**: Contributions to a source code repository that uses a distributed version control system are commonly made by means of a pull request or merge request (synonyms). The contributor requests the project maintainer to pull their changes, hence the name "pull request". The maintainer has to merge the pull request if the contribution should become part of the source base.
 * **Repository**: In version control systems, a repository is a data structure that stores metadata for a set of files or directory structure.
-* **Working copy**: The working copy is the local copy of files from a repository. All work done to the files in a repository is initially done on a working copy, hence the name.
+* **Working copy**: The working copy is the local copy of files from a repository. All work done to the files in a repository is initially done on a working copy, hence the name.
+
+[Git commands cheat sheet](https://training.github.com/downloads/github-git-cheat-sheet.pdf)