Welcome to the Turing Data Safe Haven project repository!
Thank you for being here and contributing to the project. It can truly only succeed with a interdisciplinary team working together.
The point of these contributing guidelines are to help you participate as easily as possible. If you have any questions that aren't discussed below, please let us know by opening an issue.
Been here before? Already know what you're looking for in this guide? Jump to the following sections:
For the Data Safe Haven project, we follow a DevOps development philosophy. This means different things to different people, but the definition that we're using is best summed up here.
This is a software development method which focuses on:
- communication
- integration
- collaboration
between the development team and the operations team to enable rapid deployment of products. The most pertinent features of the DevOps methodology for this project are:
- focus: operational readiness
- structure: separate development and operations teams
- duration: benchmarks around stable releases
- emphasis: taking software which is ready for release and deploying it in a reliable and secure manner
- documentation: documenting processes is a key part of the development cycle
- automation: maximal automation is the primary goal
- quality: full integration testing each time features are added
Although we are not following an Agile workflow, we still think that the following features are important:
- No work that is not documented in an issue on GitHub
- All policy documents, guidelines, tutorials, code and its documentation to be stored and maintained in this GitHub repository
- Issues to be triaged at regular project meetings with the next milestone release in mind
The goal of the project meetings is to reflect on how ongoing work is proceeding and to plan the next section of work. During the project meetings we'll start by working through the issues list and discussing any issues that are in progress. We will consider whether we should start work on any issues from the backlog.
Note that the project meeting is very explicitly not where the work gets done. It is a review, reflection and an opportunity to set goals. Discussions around particular tasks should be conducted when the work is being carried out not in the meeting.
As this team is distributed, not working full-time on this project and often working asynchronously, we do not have any form of daily meeting or stand-up The best way to work around this absence is to commit to sharing updates as regularly as possible. Please see the section on project management through issues below on how to do this via GitHub.
git is a really useful tool for version control. GitHub sits on top of git and supports collaborative and distributed working.
We know that it can be daunting to start using git and GitHub if you haven't worked with them in the past, but the team are happy to help you figure out any of the jargon or confusing instructions you encounter! ❤️
In order to contribute via GitHub you'll need to set up a free account and sign in. Here are some instructions to help you get going.
We use the Gitflow Workflow.
This means that:
- checking out the
latestbranch, will give you the latest tagged release - the
developbranch, which is the default branch of the repository, contains the latest cutting-edge code that has not yet made it into a release - releases are made by branching from
developinto a branch calledrelease-<version name>- deployment is tested from this release and any necessary integration changes are made on this branch
- the branch is then merged into
latest(which is tagged) as the next release and intodevelopso that any fixes are included there
- we prefer to use merge commits in order to avoid rewriting the git history
Discussions are the best place for informal talk about the project You should feel welcome to create a discussion on any relevant topic, without the formality of an issue. Good examples of discussions are:
- Any questions
- Possible bugs (does anyone else have this problem?)
- Looking for collaborators
- Community support
Issues are best used for tracking development work. This is because issues integrate well with GitHub development tools like projects, pull requests, assignments and so on. Each issue should ideally represent a well-defined, self-contained piece of work suitable to become a single pull request. Good examples of issues are
- Bug reports with technical detail
- Feature requests
- Specific ideas for changes
When opening an issue, pick a suitable template (if possible) to make the process easier.
GitHub has a helpful page on getting started with writing and formatting on GitHub.
Most of the writing that you'll do will be in Markdown.
You can think of Markdown as a few little symbols around your text that will allow GitHub to render the text with a little bit of formatting.
For example you could write words as bold ( **bold** ), or in italics ( *italics* ), or as a link ( [link](https://youtu.be/dQw4w9WgXcQ) ) to another webpage.
GitHub issues render markdown really nicely.
The goal is to allow you to focus on the content rather than worry too much about how things are laid out!
Please regularly check out the agreed upon tasks at the [issues list][https://github.com/alan-turing-institute/data-safe-haven/issues].
Every issue should have labels assigned to it from the following scheme.
At least one label from each category ( type , affected and severity ) should be assigned to each issue - don't worry if you need to change these over time, they should reflect the current status of the issue.
| Category | Labels |
|---|---|
| type |      |
| affected |   |
| severity |     |
Other labels which may or may not be relevant are meta labels (for collecting related issues) and the "good first issue" label for signalling issues that new contributors might like to tackle.
If an issue is closed without being completed, one of the closed labels should be attached to it to explain why.
| Category | Labels |
|---|---|
| meta |      |
| other |  |
| closed |    |
If you have an idea for a piece of work to complete, please open an issue. If you have been assigned an issue, please be ready to explain in the project meeting what your progress has been. In a perfect world you'll have completed the task, documented everything you need to and we'll be able to close the issue (to mark it as complete).
The name issue comes from a concept of catching errors (bugs 🐛) in software, but for this project they are simply our tasks.
They should be concrete enough to be done in a week or so.
If an issue is growing to encompass more than one task, consider breaking it into multiple issues.
You can think of the issues as conversations about a particular topic.
GitHub's tagline is social coding and the issues are inspired by social media conversations.
You can mention a user by putting @ infront of their github id.
For example, @KirstieJane will send a notification to Kirstie Whitaker so she knows to visit the issue and (for example) reply to your question.
Alternatively (and this is encouraged) you can use the issue to keep track of where you're up to with the task and add information about next steps and barriers.
As one of the goals of this project is to build a secure infrastructure for data storage and analysis, our project will very likely include some code with security vulnerabilities! Therefore we're keeping the repository private until we're confident that our work is secure.
Please note that the plan is to make the contents of this repository openly available. Please be considerate of the content you add and use professional and inclusive language at all times.
As we're working in a private repository you may not be able to see the repository if you aren't signed in. So if you see a 404 page and you're confident you have the correct url, go back to github.com to make sure that you're signed into your account.
To contribute to the codebase you'll need to submit a pull request.
If you're updating the code or other documents in the repository, the following steps are a guide to help you contribute in a way that will be easy for everyone to review and accept with ease 😎.
This allows other members of the Data Safe Haven project team to confirm that you aren't overlapping with work that's currently underway and that everyone is on the same page with the goal of the work you're going to carry out.
This blog is a nice explanation of why putting this work in up front is so useful to everyone involved.
Follow the instructions here to fork the Data Safe Haven repository.
This is now your own unique copy of the Data Safe Haven repository. Changes here won't affect anyone else's work, so it's a safe space to explore edits to the code or documentation! Make sure to keep your fork up to date with the upstream repository, otherwise you can end up with lots of dreaded merge conflicts.
Try to keep the changes focused. If you submit a large amount of work in all in one go it will be much more work for whomever is reviewing your pull request. Help them help you 😉 If you feel tempted to "branch out" then please make a new branch and a new issue to go with it.
Once you submit a pull request, a member of the Safe Haven project team will review your changes to confirm that they can be merged into the codebase.
A review will probably consist of a few questions to help clarify the work you've done. Keep an eye on your github notifications and be prepared to join in that conversation.
You can update your fork of the data safe haven repository and the pull request will automatically update with those changes. You don't need to submit a new pull request when you make a change in response to a review.
GitHub has a nice introduction to the pull request workflow, but please get in touch if you have any questions 🎈.
The docs, including for older releases, are available here.
You should follow the same instructions as above to make a change with a pull request when editing the documentation.
To preview your changes, you can build the docs locally. See docs/README.md.
Take a look at the full list of contributors on our README.
We use @all-contributors to maintain the contributor list on the README, however we do not use the GitHub bot.
You should follow the same instructions as above to make a change with a pull request when adding a new contributor.
To add new contributor to the README table, see the all-contributors CLI documentation and use the CLI to add the new contributor, then make a pull request with your changes.
You can get in touch with the development team at safehavendevs@turing.ac.uk.
You're awesome! 👋😃
Based on contributing guidelines from the BIDS Starter Kit project. Reused under the CC-BY license.