Version Control

Note, these are guidelines used by the SCD Cloud Operations Group. They are being presented externally as they may be useful for those developing their own software, they are not being provided with the intention of the Cloud Team reviewing your code - unless you are contributing to one of our repositories.

It is important to use version control throughout the software development lifecycle. It provides the following benefits:

facilitates collaboration
enables easy coordination of parallel work
preserves integrity of codebase by keeping a historical record of changes

Repository Layout

Organising a Repository is generally up to the discretion of the repository owner. But usually a repository will contain:

A README file to communicate important information about the project. see README guidelines
A folder for source code (usually src)
A folder for tests (usually tests) - recommended to be separate from src but can be a subfolder
.gitignore file.

Please see some of our maintained repositories as examples: https://github.com/stfc

Branch Protections Rules

When setting up a repository it is best practice to set up branch protections in order to prevent any changes being pushed to the main branch without a pull request.

To add branch rules:

Go to Setting in the repository
Select Branches in the left hand column

Example in cloud-grafana-dashboard repo

Then select add rule

You should see a page similar to this:

For Branch Name Pattern enter the name of the branch to protect e.g. main
Select Require a pull request before merging
- Select Require approvals like this:

Then press create and now you should have a branch protection rule on main

Maintaining Access

If you are creating a new repository and have set up branch protection rules for main, you should update who has access to modifying the repository within the team. This is so other members of the team can merge PRs to the repo if you are away.

Go to Settings and Select Collaborators and Teams
Then select Add people and search for the GitHub username for a Cloud Team member (e.g. David, Megan, Anish) to add and add the member and give them an Admin role.
Then select Add team and search for stfc/cloud and add the team to the repository and give them the Maintain role. Now everyone in the team can maintain the repository and can merge any pull requests.

Pull Request Template

When organising a repository, it is good to include a pull request template that should be used when pull requests are created.

Adding a pull request template can be done as follows:

Create a directory .github
Create a markdown file pull_request_template.md

The template can be similar to this one:

### Description:

<!--
This should be a brief description of the PR. Details should be contained in commit messages

-->

### Additional Notes

<!-- This section can be removed if not required 

-->

---

### Submitter:

Have you:

* [ ] Checklist for submitter


### Reviewer:

As part of reviewing this PR...

* [ ] Checklist for reviewers

Here is an example of a PR template in the Cloud Grafana Dashboard Repository:

Pull request templates can help with standardizing how PRs are submitted and outlines the main checks the submitter and reviewer should do before the PR is merged.