David Klein (dklein@pik-potsdam.de), Kristine Karstens (karstens@pik-potsdam.de) 15 February, 2020
REMIND and related R packages are published as open-source software on GitHub. There are various workflows, how to use GitHub for collaborative software development. We want to give some general remarks on our prefered one. Note the following:
-
Git is a free and open source distributed version control system designed to handle everything from small to very large projects with speed and efficiency (from: https://git-scm.com/ - very good help, documentation, tutorial page for git).
-
GitHub is an US American company (owned by Microsoft) that provides hosting for software development version control using Git. (GitLab, SourceForge and various more are open-source alternatives to GitHub.)
The goal of this exercise is to set up REMIND for collaborative working. After completion of this exercise, you'll be able to:
- "Fork" and "clone" your personal REMIND repository
- Keep your personal repository up-to-date with the REMIND main repository
- Understand the basic workflow including pull requests and branches.
- Have heard some very basic git commands and know where to find more help.
Every code development (even bugfixes) will be merged into our main (called "upstream") repository under https://github.com/remindmodel/remind with the help of so called pull requests. Pull requests give us control over the changes entering our branches. To create a pull request, we use personal or institutional forks. They have to be kept up-to-date with our upstream repository (the original remindmodel fork).
Exercise: Visit us on https://github.com/remindmodel/remind and create your own fork by clicking at 'fork' (at the upper right).
To run REMIND on your local machine or a high-performance cluster, you have to clone (download) the code from your fork.
This can be done with your preferred git client (e.g. the git command line program or GitHub Desktop).
We recommend to upload an ssh-key and use ssh to connect to GitHub.
If you want to use the git command line program in windows, open a git bash as follows:
open the file explorer, right-click on the folder you want to execute the git commands in and choose "Git Bash Here" from the context menu.
You need to have git installed.
Because of a storied history, the full REMIND repository is about 1.2 GB in size; therefore, it is recommended to only clone (download) the parts you need, or use a local reference repository if available.
If you have a local reference available (e.g. on the PIK cluster, or because you cloned REMIND previously), we strongly recommend to use it to avoid re-downloading and duplicating all data.
On the PIK cluster, use the cloneremind command like this:
cloneremind git@github.com:<yourname>/remind.gitwhere you replace <yourname> with your GitHub username.
If you are not on the PIK cluster but have a reference clone available, use
git clone --reference /path/to/reference/clone git@github.com:<yourname>/remind.gitwhere you replace /path/to/reference/clone with the path to your existing REMIND clone and <yourname> with your GitHub username.
Do not delete the reference.
If you don't have a local reference available, you can filter large files when cloning REMIND. This saves a lot of time downloading everything and also saves space for storage, in exchange for needing to automatically download things on-demand if you want to examine old versions of remind.
Using the git command line program, use
git clone --filter=blob:limit=1m git@github.com:<yourname>/remind.gitwhere you replace <yourname> with your GitHub username.
If you don't care for download time and storage requirements, or want access to all historical versions of REMIND without internet access, just clone normally.
Using the git command line program, use
git clone git@github.com:<yourname>/remind.gitwhere you replace <yourname> with your GitHub username.
Exercise: Visit your fork and clone the repository at your machine.
When you start making your first changes to the code at your local copy, we strongly recommend to read a tutorial to get familiar with the basic commands in Git. We have compiled a typical workflow at the end of this tutorial (section 3) (you can also have a look on 'git cheat sheets' like https://about.gitlab.com/images/press/git-cheat-sheet.pdf).
After you have added your changes locally, push (upload) them to your personal remote repository.
To keep your fork up-to-date with the upstream repository you can use
the GitHub interface. Via Compare you can check if the
upstream is some commits ahead. If so merge these new changes into
your fork.
You can also do this merging procedure in your local copy by adding both your fork and the upstream repository as so called 'remotes' to your local repository.
Exercise: Check, if there is anything to merge from the upstream repository into your fork. If so, merge it into the local clone of your personal fork.
After you have committed your changes locally, merged the latest updates from the remote upstream repository and pushed the result to your remote personal repository it is time to get it integrated into the remote upstream repository. Instead of pushing them directly into the remote upstream repository we use so called pull requests. Pull requests are proposed changes to a repository submitted by you and accepted or rejected by a repository collaborator. Like issues, pull requests each have their own discussion forum.
Note: it is rather useful to do your work on feature branches rather than on the default develop branch. This
helps you keep better track of your work and also helps your colleagues understand easier what your recent pull request
was about. So naming your branch "bugfix_make_feature_XX_operational_again" will greatly help. See below for more on
working with branches.
