Skip to content

Latest commit

 

History

History
47 lines (37 loc) · 5.17 KB

version-control.md

File metadata and controls

47 lines (37 loc) · 5.17 KB
Raw

Sharing source code with version control

Below, you can learn how to get started with version control, as well as find guides and guidelines for typical tasks undertaken by Amsterdam UMC researchers.

Getting started

A basic guide to git is available via the Software Carpentry. Slightly more advanced guides can be found at the Code Refinery and The Turing Way.

Where to host your code repository?

Please host your repository under the Amsterdam UMC organization on GitHub. To get access to this organization, get in touch with Thomas Pronk.

How to name your code repository?

Please keep the following in mind:

  • Only use lower-case characters for words; abbreviations can be in UPPER-CASE
  • It is not required to add Amsterdam UMC or your team name to your repository name

For example, if you create a repository for a software application called "Epic EEG Tool", then name the repository epic-EEG-tool. Under the Amsterdam UMC organization, the URL to your repository would then look like this: https://github.com/AmsterdamUMC/epic-EEG-tool. Not that the team name is not part of the URL, since teams are not visible for non-Amsterdam UMC users. You may include the team name in the repository name, but it is not required. If the epic-EEG-tool were from department DptX, you would still get https://github.com/AmsterdamUMC/epic-EEG-tool us URL. This is ok: https://github.com/AmsterdamUMC/dptx-epic-EEG-tool. These two are allowed but are superfluous and therefore not recommended: https://github.com/AmsterdamUMC/AmsterdamUMC-epic-EEG-tool andhttps://github.com/AmsterdamUMC/AmsterdamUMC-dptx-epic-EEG-tool

What not to put on GitGub

The guidelines in these pages concern the publication of code written by Amsterdam UMC employees, so as to share this code with the world. Therefore, use the Amsterdam UMC GitHub for code that was written as part of your employment for Amsterdam UMC (or AMC/VUmc). If your work was a collaboration between Amsterdam AMC and another institution: fine. But keep your hobby projects somewhere else. Moreover, do not put on GitHub or other public version control platforms any code:

  • That would violate the intellectual property rights of the owner. Of course, your repository may contain libraries, components, image files, and source files that originated partly or entirely from outside the Amsterdam UMC. But their license should be compatible with the license of your repository.
  • As a private repository. Cloud-based version control is not highly secure. Hence, if you want a private repository for development of your code (as opposed to sharing your code with the world) you should not use the Amsterdam UMC GitHub if security is important. Either store the repository on a share (afdelingsschijf) or request access to the Amsterdam UMC Gitlab, which is hosted on the Amsterdam UMC intranet (ask the ICT service desk).

How to prevent accidentally committing personal/sensitive data to the repository?

To be sure that no personal or sensitive data ends up in your repository, we recommend setting up multiple lines of defense, as outlined below.

1. Have a directory structure that separates code from data

Assume our example Epic EEG Tool is part of a project (called "Epic EEG Project") that also includes data, then create a folder structure like this.

# The root directory of your project
/epic-EEG-project/
# The code of your project; this will be under version control
/epic-EEG-project/epic-EEG-tool/
# The data of your project
/epic-EEG-project/data/

Structuring your project as above will ensure that data is less likely to accidentally end up in the directory under version control (/epic-EEG-project/epic-EEG-tool/), and so end up on GitHub.

2. Add the extensions of your data files to .gitignore

The .gitignore file specifies which files and directories are ignored by git (details here). Imagine our Epic EEG Project includes participant data files with the extensions .bids and .csv. A .gitignore file like the one below would exclude these files from version control.

*.bids
*.csv

3. Be careful when pushing to GitHub

Whenever you push a set of changes to your remote repo (GitHub), take a quick look to check whether no personal/sensitive data is accidentally included. Be careful with secrets (e.g., passwords, API keys, OAuth IDs), personally identifiable information (e.g., email addresses), and internal server names.

When publishing a private repository as a public repository, just removing sensitive data from your files does not suffice; after all, the removed data is still in the version control system. Therefore, create a new local repository, copy the files you want to publish to the new repository, and push it to GitHub. If this is not acceptable because you really must retain the version history but without the sensitive data, follow these guidelines.