diff --git a/modules/version-control/slides-version-control.md b/modules/version-control/slides-version-control.md index bef5f927..15ab4afa 100644 --- a/modules/version-control/slides-version-control.md +++ b/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...
- independent changes + independent change
@@ -72,9 +72,58 @@ The changes are stored along with some useful metadata. A set of changes, along 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. +=== + + +## Merge conflicts + +However, if multiple contributors work on the same thing... + +```bash +This line contains a typos. +``` + + +... then "merge conflicts" may arise: + + +```bash +<<<<<<< contributor1 +This line contains typos. +======= +This line contains a typo. +>>>>>>> contributor2 +``` + + +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. + +=== + + +## 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 + + + +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 diff --git a/modules/version-control/version_control_exercise.md b/modules/version-control/version_control_exercise.md new file mode 100644 index 00000000..f08d4c5d --- /dev/null +++ b/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 diff --git a/modules/version-control/version_control_exercise1.md b/modules/version-control/version_control_exercise1.md deleted file mode 100644 index b6b48a2b..00000000 --- a/modules/version-control/version_control_exercise1.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: Case Study -type: exercise -order: 3 ---- - -## Exercise: Case Study - -**Case study**: A researcher comes to you with a problem of how to keep track of different versions of code. - -What advice would you give the researcher to keep track of changes of their scripts/code and when best to do this. -Would you advise them to work with a local or remote version control system? \ No newline at end of file diff --git a/modules/version-control/version_control_exercise2.md b/modules/version-control/version_control_exercise2.md deleted file mode 100644 index 5c48823e..00000000 --- a/modules/version-control/version_control_exercise2.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: Tool search -type: exercise -order: 4 ---- - -## Exercise: tool search - -In breakout groups of 3-4 people, identify 3 commonly used version control systems or tools that you have heard of (or used yourself) (for example: Git). -Together, search for a resource (such a website, or handbook) for each tool that helps explain how to use its key features. \ No newline at end of file diff --git a/modules/version-control/version_control_resources.md b/modules/version-control/version_control_resources.md index 2e7018a2..d41c16cc 100644 --- a/modules/version-control/version_control_resources.md +++ b/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/ \ No newline at end of file diff --git a/modules/version-control/version_control_terminology.md b/modules/version-control/version_control_terminology.md index 44c2dbdb..b6981d63 100644 --- a/modules/version-control/version_control_terminology.md +++ b/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. \ No newline at end of file +* **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)