Purpose: This page sets out guidelines to follow when using git with projects in R and RStudio.
Adhering to these guidelines will make life easier for yourself, the team, and any future contributors to the project.
Git should be employed whenever work that is being done is going to be shared, either immediately or in the future. Ideally, projects should be begun with git, so there is a complete history of the project. Where this isn't possible, an initial commit message should set out the state of the project when the 'git history' begins.
Repositories
- Principle: Each repository/repo should cover an entire project, and the name should be descriptive.
e.g. dashboard-hkdistrictcouncillors
Branches
- Principle: Each branch should have a single purpose.
- Frequency: Every time you want to work on part of a project, create a branch for it.
- Naming Convention:
type/name- this lets branches of the same type be grouped together in VSTS- Choose short and descriptive names
feature/b1is not descriptivefeature/branch-to-implement-the-functionality-discussed-on-tuesdayis not shortfeature/dynamic-filteris short and descriptive - Use hyphens to denote spaces in your branch name
- Don't include your name on the branch. This is recorded elsewhere by git.
Note, this is for branches that you are sharing with others. If you are just experimenting on your local machine then feel free to use whatever convention you like. Anything pushed to GitHub must follow these conventions.
Branch Types
Note this is not an exhaustive list:
feature Additional functionality or features
devops Software development/IT operation-related changes
bugfix Fixing an error
data Updating data or data connections
format Changing the format/layout
document Create documents for community standards
Any suggestions, let us know!
E.g. feature/drill-down
Commit
- Principle: Include "what the commit does" as well as "why it does it" if the "what the commit does" message is not sufficient. Like Twitter, any commit message cannot be longer than 80 characters.
- Frequency: Commit often and early, to ensure you don't lose any work. Don't worry about your
git logorgit nllooking ugly. You can clean this up afterwards. - Naming Convention: Should follow the below form, where <type> and are mandatory, whilst and are optional.
- If and are present, is mandatory.
<type>: <subject>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>
Most commits will be of the form <type>: <subject>. For example:
feat: Add option to filter on Local Authority
fix: Convert grades to factor for correct ordering
perf: Remove all for-loops and replace with vectorised functions
(Mandatory)
- Must take one of the following:
feat A new feature
fix A bug
docs Documentation only changes
style Changes that do not affect the meaning of the code *e.g. white-space, formatting*
refactor A code change that neither fixes a bug or adds a feature
perf A code change that improves performance
test Add missing tests
chore Changes to build process or auxiliary tools and libraries such as documentation generator
(Mandatory)
- Should be a succinct description of the change, and follow the conventions below:
- Use the imperative, present tense. *e.g. 'change', not 'changed' or 'changes'
- Capitalise the first letter after
<type> - Don't use full stops
(Optional)
- Should include motivation for commit and contrast this with previous behaviour
- Use the imperative, present tense
(Optional)
- References any GitHub work items that this commit addresses
Example
feat: Include observe and handler expressions
Key requirement of dashboard project to get drill-down functionality.
closes #1234
Pull Requests
A 'Pull Request' is a request by a developer to have their work (in a branch) merged into another branch, usually master/main. For example, when a particular feature/branch is complete, it needs to be merged with master/main to allow the other developers to use it.
Note that a pull request is a GitHub artefact, not a git one!
When you update your branch (by pushing your changes to the remote branch on GitHub), you will see you have the option to open a new pull request; this is on the right hand side of the 'Branches' tab, under Code, in GitHub.
This brings up a form, asking you for a title, a description, reviewers and linked work items.
Title
The title should generally be left as it is by default - it is descriptive of the branches involved in the merge.
Description
Use this box to describe:
- What the overall purpose of the branch being merged is (Summary)
- The details of what has changed, as a bullet list (Details)
- What you would like the reviewers to check (To Check)
- How they should go about doing so (How to Run)
The Description box supports markdown, so use **, # and other markdown tags to format your pull request nicely. It doesn't take long, and it makes it much much easier to read!
Reviewers
Here you should add the profiles of any collaborators you want to review your changes. They will be sent an email to tell them that they have been asked to review a pull request, with a link to the PR in GitHub.
Linked Work Items
Use this field to link any work items from Issues (e.g. Feature requests or Bugs). These will be visible to any reviewers, so they can see the wider context of what you're trying to do. If and when the PR is approved and completed, you will then have the option to automatically close these linked work items, saving time on project management.
If you are asked to review a Pull Request
You can look at the diff of the code in GitHub (this is where new code appears in green, old deleted code in red) and you can add comments to the diff here. You can also (and you should) clone the repo (using git clone '<url>') and test it out locally. This also means any further pull requests you are asked to review can simply be pulled from the remote.
You have the option to 'Approve', 'Approve with Suggestions', 'Wait for Author' or 'Reject' a Pull Request. Comments and Suggestions form a thread at the bottom of the Pull Request page.
To complete a pull request
To complete a pull request once it has been approved, click the blue 'Complete' button in the top right hand side. This will perform the merge and generate a merge commit, with a link to the PR on the right hand side.
It is not best practice to perform the merge manually from the command line, as this doesn't create the integrated links within VSTS.
References
These guidelines have been influenced by the following sources:
- GitHub Git Style Guide
- iwisich Git Style Guide which was inspired by Conventional Commits
- Gravity Department Blog
Additional Readings
High-level Git tutorials:
Git cheatsheets: