Chapter 3 Collaborative

It is vital that we’re able to collaborate across projects, to share both workload and expertise, and that this collaboration is possible both simultaneously and over time.

3.1 Version control

Code should be version controlled using Git and checked into Github. You can find a guide to using Git with R here. Within DASD we follow Github flow for our projects.

Github flow

Github flow is a working practice that helps to maintain overall code quality, facilitate collaboration on a single project and protect the codebase. We have tweaked it a little from what is described on GitHub.

There are 6 steps to our process:

1. Create or clone a repo.

For example, to clone this repo.
git clone git@github.com:moj-analytical-services/our-coding-standards.git

2. Create an issue in Github that describes what you’re working on To create an issue, use the Github website.

3. Create a new branch for the work you’re about to do, with a name corresponding to the issue

To create a new branch and switch onto it.
git checkout -b my-new-sensibly-named-branch

4. Make some commits on the new branch.

Make some changes then stage each file you have changed - e.g. file1.txt and file2.txt.
git add file1.txt
git add file2.txt
etc

Commit your changes using a descriptive commit message.
git commit

This will take you into your default text editor
Write a descriptive commit message

Note: If you have not configured your text editor, you may get stuck in Vim. You can exit using the following command: :q!. Then configure your default text editor for Git

git config --global core.editor <my-favourite-text-editor>
 Then try again
git commit

5. When you’re ready, submit a pull request and wait for peer-review.

push your branch to the remote repo
git push origin my-new-sensibly-named-branch
then go to Github, open a PR and invite at least one reviewer

Make sure that you reference the issue in your pull request, by using the hash (#) symbol - see here for further guidance. This makes it easy in future to see what changes were made to the code in response to the issue.

6. To make further changes, just make more commits on the same branch and push them to the remote repo again.

7. Once peer review is complete, and any comments addressed, merge into the master branch using a rebase.

8. The version of master on Github is now ahead of the version of master on your local machine. Bring your local version up to date using git checkout master, git pull. You are now in sync with Github, and ready to start a new branch.

The master branch should be 100% functional at all times, on any machine. Please ensure it is protected and that your tests and linters run automatically on all pull requests. A protected master branch guarantees that all pull requests have been reviewed before they are merged.

For some further reading suggest this article that explains these git commands and others in a bit more detail.

Useful Github links

• A guide to getting started with github
  
• Github guide on analytical platform guidance
  
• List of basic git commands

3.2 Share the knowledge

We also collaborate through sharing knowledge. There are a number of channels through which coding knowledge is shared in DASD:

• Slack channels (key channels are: #data_science, #r, #python, #conda)
  
• Coffee and Coding (resources here)
  
• DASD training Trello
  
• R learning resources

Further resources can be found here.