Version control guide

After reading this quick guide, and learning the basic concepts, you can check out this video tutorial. It covers a basic scenario of working on Fingreen (or Eurogreen): some new development, rebasing the changes on an updated main branch, solving the conflicts, and opening a pull request.

Git is a version control system. It means it can track differences in files and keep their history. It is most suited for tracking text files (including code), because the differences are easy to read and when a file has conflicting changes from multiple development tracks, these conflicts can be solved. However, it can also track binary files, like spreadsheets or images or anything else.

A git repo is a directory (“folder”) on your computer that includes files tracked by git.

One can work with git

• on the command line. For windows I recommend git bash, so you can work with git just as if you were on Linux or Mac. For Linux and Mac, normal git is available.
• with graphical user interfaces. Git Gui comes bundeled with git bash in Git for Windows. One option is GitHub desktop, which has the downside of favoring github over other remote repositories and using confusing terminology which differs from actual git. Eg. RStudio, Positron and VSCodium include great graphical interfaces for git (VSCodium is VSCode without the Microsoft branding and telemetry).

It takes some effort to learn to use git effectively. I encourage to set aside a few hours to learn the basics of git on the command line. This will also make using git though a graphical interface much easier. The payoff is thousandfold in saved confusion and ease of working, trying out things, fixing things and collaborating. A good tutorial for beginners can be found here.

Github is a hosting platform for remote repositories, also called a “forge”. It means that it can store your git-tracked project files outside your computer and easily work on them together with others. It also has a nice interface for interacting with the repository, as do other forges. Github is owned by Microsoft. There exist other similar platforms, such as Codeberg, which is free.

So far, Eurogreen and Fingreen are hosted on Github. New projects could benefit from using Codeberg, with a better free featureset and European ownership of the platform.

There are many ways to organize work with git. What is suitable depends on the context. For our context, I think that a workflow called Github Flow is the best fit.

This branching strategy has nothing to do with Github specifically, except for it's origin. It is a simple strategy, and I think it is best suited for working on Eurogreen. I give a simplified description of the strategy, in our context:

1. The main branch is where a working version of the model always lives.
2. Any new features or changes are worked on separate feature branches, eg. feature/new-pension-logic that are branched off from main. When work on the feature is done, it is time to check whether main has received any updates since. a) In case it has we rebase the feature branch on to the updated main before proceeding to b. b) In case not, we can immediately create a pull request to merge our changes into main.
3. Small changes/fixes can be done on separate hotfix/fix-issue-x branches, or even directly on the main branch.

Instead of just pushing our changes directly into main, it is usually a good idea to open pull requests instead. They could actually be called merge requests, because the idea is to merge some changes from one branch into another. A pull request can be viewed and commented in Github, and it is a good idea to have another developer review the changes. This encourages better quality and compliance with common guidelines, improves catching bugs early, and the team is better kept up to date on what is going on in the model. Creating a pull request is covered in the video tutorial.

Conflicts can arise if we try to merge or rebase our changes with someone else's changes: both modified the same file and now git does not know how to combine the changes or which one to prefer. A basic example of conflict resolution is shown in the video tutorial. Avoid simultaneous work on the same views in the model, beacause conflicts in the visual section of the model file are much harder to solve.

Upcoming

Usually, it is better to commit often rather than sparsely. One rule of thumb is to commit whenever you make some kind of a “decision”. Often developers commit, when they finish working on the smallest change that still yields a functional result. It probably makes no sense to commit after every line or variable definition, if that line itself does not result in a meaningful change of function or leaves the model in a dysfunctional change.

A commit message should state in concise imperative form what change it implements. Do:

# Do:
git commit -m "Implement new logic for calculating pensions by gender and skill."
## Do NOT:
git commit -m "Changed eurogreen.mdl"
## also don't
git commit -m "some work"
# also don't
git commit -m "I wrote here a full novel describing everything: Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum."