Thanks for thinking about contributing! If you make a significant contribution to this book we will happily add you to the list of authors to credit your effort.
The Reproducible Analytical Pipelines (RAP) companion makes use of hosting our RAP_companion repo using Github pages.
These instructions draw heavily from the document by Chase Petit on Github.
The RAP companion is being developed as a community project whereby colleagues in Government Departments implementing the tools and techniques recommended by the RAP (aka DataOps) paradigm have an accessible knowledge repository to share-and-learn best practice from.
If contributing using the below methodology seems too difficult then you can always share your work with us via email and we can incorporate it into the book for you. However, we recommend you attempt to use git and Github as learning how to collaborate via this medium is a key skill in RAP best practice.
See Hadley Wickham's intro here.
You need to setup git, get a Github account and access Github.
Hadley Wickham also provides a detailed walkthrough of how to set up and use git and Github within R Studio.
You will need to set up authentication to GitHub from Git as well.
A fork is a copy of a repository. Forking a repository allows you to freely experiment with changes without affecting the original project.
Head over to the GitHub page and click the "Fork" button (in the top right hand corner). It's just that simple (forking it does what's described in the figure below - it makes a copy on Github "in the cloud" for you, of another repo). Once you've done that, you can use your favourite git client to clone your repo or just head straight to the command line (recommended; for forking in git see here for an alternative guide to forking):
# Clone your fork to your local machine
git clone [email protected]:USERNAME/rap_companion.gitCloning creates a local copy of your forked repo on your local machine.
All this esoteric git parlance makes life difficult for those new to version control. We provide a diagram (based on this blog) to elucidate the git terms you will be using throughout this Github fork and pull request workflow (this workflow is suitable for an Open project with many potential collaborators).
Look at the figure above and find each of the keywords as described below. (Inspired by this guide).
-
Repository is a collection of files that are tracked together by the git protocol, also known as a repo
-
Remote vs Local is the distinction between files (a repo) that live in a server, such as one managed by Github, and one that lives directly on your machine
-
Fork is a remote repo that is a direct copy of another remote repo
-
Clone is to bring down all files from a remote repo to your machine locally
-
Remote is an alias in your Github repo that points to a remote Github repo via its web address
-
Origin is the standard naming convention for your remote repo
-
Upstream is the standard naming convention for the original remote repo
While this isn't an absolutely necessary step, if you plan on doing anything more than just a tiny quick fix, you'll want to make sure you keep your fork up to date by tracking the original "upstream" repo that you forked (this is because it is in constant development). To do this, you'll need to add a remote:
# Add 'upstream' repo to list of remotes
git remote add upstream https://github.com/ukgovdatascience/rap_companion.git
# Verify the new remote named 'upstream'
git remote -vWhenever you want to update your fork with the latest upstream changes, you'll need to first fetch the upstream repo's branches and latest commits to bring them into your repository:
# Fetch from upstream remote
git fetch upstream
# View all branches, including those from upstream
git branch -vaNow, checkout your own master branch and merge the upstream repo's master branch:
# Checkout your master branch and merge upstream
git checkout master
git merge upstream/masterIf there are no unique commits on the local master branch, git will simply perform a fast-forward. However, if you have been making changes on master (in the vast majority of cases you probably shouldn't be - see how to create your own development branch, you may have to deal with conflicts. When doing so, be careful to respect the changes made upstream.
Now, your local master branch is up-to-date with everything modified upstream. Still don't get it? For an alternative visual guide see here.
Whenever you begin work on a new feature or bug-fix, it's important that you create a new branch. Not only is it proper git workflow, but it also keeps your changes organized and separated from the master branch so that you can easily submit and manage multiple pull requests for every task you complete.
To create a new branch and start working on it:
# Checkout the master branch - you want your new branch to come from master
git checkout master
# Check your master branch is up to date
git pull
# Create a new branch named feature/new_branch (give your branch its own simple informative name)
git branch feature/new_branch
# Switch to your new branch
git checkout feature/new_branchNow, go to town hacking away and making whatever changes you want to. When you're happy with the changes you've made to the book or created a new Chapter then you need to render the book.
This done automatically using Travis, interacting with Github, to execute some code when the pull request is accepted; it automatically builds the book to the gh-pages branch which then updates the RAP companion.
Prior to submitting your pull request, you might want to do a few things to clean up your branch and make it as simple as possible for the original repo's maintainer to test, accept, and merge your work.
If any commits have been made to the upstream master branch, you should rebase your development branch so that merging it will be a simple fast-forward that won't require any conflict resolution work.
# Fetch upstream master and merge with your repo's master branch
git fetch upstream
git checkout master
git merge upstream/master
# If there were any new commits, rebase your development branch
git checkout feature/new_branch
git rebase masterNow, it may be desirable to squash some of your smaller commits down into a small number of larger more cohesive commits. You can do this with an interactive rebase:
# Rebase all commits on your development branch
git checkout
git rebase -i masterThis will open up a text editor where you can specify which commits to squash.
If your pull request fixes a specific issue, Github can automatically close that issue based on the commit message as described by Hadley Wickham.
Once you've committed and pushed all of your changes to GitHub, go to the page for your fork on GitHub, select your development branch, and click the pull request button. If you need to make any adjustments to your pull request, just push the updates to GitHub. Your pull request will automatically track the changes on your development branch and update.
There's nothing better than receiving a pull request! Thanks for your contribution to our project. :)
The review of the pull request will be carried out by the owners of the repo from which you forked; in this case members of the ukgovdatascience team. Broadly our methodology will follow that described by Hadley Wickham here.
If you contribute a significant amount to this project we will happily add you to the list of authors, crediting you for your efforts and recognising how you are engaged with fulfilling your Civil Service objectives.
- Use a consistent style; this is a good place to start!