--- title: Version Control Slides type: slides order: 1 --- # Version Control What is version control and why should I use it? note: You are probably using version control every day. Word and other documents store a history of changes for you, which you can undo. Google docs have an even more intricate system of reviewing history, etc. === ### Version Control *A system that organizes and records changes to a (set of) file(s) and/or their metadata over time, allowing one to revisit specific versions later.*

Piled Higher and Deeper by Jorge Cham

note: Strictly speaking, this is a form of version control: separate versions are stored, commented on, and organized in some way. Lets see a more practical, systematic, and robust way of doing this... === ## Documents are...

... a series of changes

note: In version control systems, documents start with a base version (which may or may not be empty) and record all the changes that happened on top of that base version. Because of this you can always "play back" to an earlier version or compare separate iterations, without having to store near-identical variations of the same documents. == ## Software is... ... a collection of one or more documents. - Code - Documentation - Environment & infrastructural files - ... note: Any piece of code is nothing more than a (plain) text document, not too different from a word file. The same is generally true for most other files comprising the software. Therefore, changes are excessively easy and computationally efficient to track. Even complex (binary, data, image, ...) files can ultimately be rendered in plain text, and therefore tracked using version control. Although changes are not easy to visualize and it will require multiplying the data storage for each change. === ## Changes... ... are stored using a version control (VC) system (usually `git`).

A single unit of change is called a [commit](version_control_terminology), and is typically associated with a brief [commit message](version_control_terminology), [commit hash](version_control_terminology) (SHA), and other metadata. note: Commit hashes are unique references to a commit, while commit messages are human readable descriptions. Other metadata can include the author(s), timestamp, etc. == ## A commit... ... can be of any size or type: - Single line additions/deletions/changes - Additions/deletions/changes of (multiple) large sections - Adding or deleting files - Moving files into different folders - ... note: A commit is the fundamental unit of change in version control, but its scope is not strictly defined. Ideally, a commit should be large enough to represent a meaningful improvement while remaining small enough to focus on a single, coherent change. Balancing these factors helps maintain clarity and makes it easier to track, review, and revert changes when needed. == ## Sequential commits... ... form a log The data structure that contains the software plus the commit history is called a [repository](version_control_terminology).

note: A good rule of thumb for commit sizing is whether you can write a clear, concise commit message summarizing the change. If the commit is too small, the message will simply describe the specific action taken. If it's too large, summarizing it succinctly becomes difficult. Striking the right balance ultimately also allows the commit log to be read almost like a history book. === ## Keeping track #### Question: Say you have dozens (hundreds, thousands, ...) of old versions, how do you manage to find a specific/useful previous version? - Effective committing (sizing & messages) - Versioning systems - Create Change logs and DOIs for stable/important versions note: We've talked above extensively about commit hygeine, so will now discuss the other 2 aspects. == ## Versioning Use a logical system to keep track of (stable) versions ... and document the system used in the repository.

Common systems:

Semantic Versioning (SemVer):

4.3.12 = major.minor.patch
pro: version numbers have a functional relevance
con: users must keep track of the precise version used

Calendar Versioning (CalVer):

2025.02.03 = YYYY.MM.DD
pro: simpler implementation
con: development is usually not as linear as this system implies

note: Not every change or addition needs a new version number; this is what commits are for. Make sure that whatever versioning system you use is also documented in the repo, so that others (and future you) can see what the logic is. == ## Change logs & DOIs Keep a human readable log summarizing the changes of each new version. Host versions on servers such as [Zenodo](https://zenodo.org/) or [GitHub](https://github.com/)/[GitLab](https://gitlab.com/) to generate a DOI.

Excerpt of release notes for ruff linter v0.8.6 note: This is the equivalent of the "commit message" at the level of a new version. There are a few (near) synonyms used for this: change log, release notes, change history, etc. However, it is separate from the commit log or commit history, as per the comment above. === ## Collaborating using VC More than one...

... source of change...

... can be merged.

note: 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. == ## Branching A project can have many [branches](version_control_terminology), which may or may not get [merged](version_control_terminology) back into the main version.

Image by: The Turing Way **What uses can you think of to create branches, other than "feature branches"?** note: The main branch is supposed to be a stable version, that one can mostly rely on to work as expected. Changes created in branches may get merged back into the stable version, or may persist (or die) as a parallel version Branches here are indicated as "feature branches", i.e. branches used while creating new features in a code base. Other uses of branches: - a sandbox or playground, for trying out different things without "damaging" the stable version - organizing/storing results alongside their different variations/settings - release management - custom/user specific changes - ... == ## Keeping a centralized repository

[The five pillars of computational reproducibility: Bioinformatics and beyond](https://www.researchgate.net/figure/Distributed-version-control-Adapted-from-48_fig2_371671830) note: Collaborative code developers often make use of a remote server (like GitHub, or GitLab) as a central repository from which all other repositories derive. But this is not the only way you can use version control to do collaborative development. Separate local repositories are similar to but distinct from individual branches of the main repository. == ## Hosting the main repository

note: Many different tools exist specifically for collaborative version control of computer source code and other simple text-based documents. Git (for version control) with GitLab and GitHub (for collaboration) are the mainstream, used by many and with lots of features. We recommend against using any of the other tools unless the users already know what they are doing or have very strong reasons for dloing so. GitLab is fully open source and offers a self-managed option, allowing organizations to host and manage their own GitLab instances on-premises or in their private cloud environments. This provides full control over data and customization. Conversely, GitHub is owned by Microsoft and uses (some) proprietary software, but is more widely used and more people will be familiar with the interface and functionality. It offers no self-managed option, but does allow for private repositories. === ## What can go wrong?

note: If changes are made to the same section (usually the same or consecutive line(s) of text) of a document a [merge conflict](version_control_terminology) 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. Resolving merge conflicts can be time-consuming and error prone, especially for large conflicts. Therefore it is a good idea for teams to agree on some basic practices to avoid creating conflicts in the first place. == ## Merge conflicts If two people change the same line... ```bash This line contains a typos. ``` ... [merge conflicts](version_control_terminology) may arise: ```bash <<<<<< HEAD (Current Change) This line contained a typo. ======= This line contained typos. >>>>>> feature-branch (Incoming Change) ``` note: If changes are made to the same section (usually the same or consecutive line(s) of text) of a document a merge 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. Resolving merge conflicts can be time-consuming and error prone, especially for large conflicts. Therefore it is a good idea for teams to agree on some basic practices to avoid creating conflicts in the first place. == ## Avoiding merge conflicts

Communication

Who is working on what?
Follow or create common standards

Frequent updates

push and pull changes regularly
Review each other's work before merging

Organized workflow

Commit hygeine and feature branches
Avoid "scope creep"

Tools are your friends

Kanban boards for task assignment
linters for style aherence

All icons from Icons8 note: Keep in mind, that it is unrealistic to prevent all conflicts. This is fine, but they will need some attention to resolve. Communication is key! === ## Key Points - Version control is like unlimited undo in MS Word... and more! - Version control streamlines working in parallel - A remote repository is often used as central hub for collaborative development - Communication is key to avoid conflicting versions of the same documents === www.esciencecenter.nl info@esciencecenter.nl 020 - 460 47 70

Software Version Control