This project uses Github Flow for its software development lifecycle. Github workflow is a simple workflow that works well for a small project with multiple developers needing to work on the code and review each other's code before merging into the main branch.
This assumes you've already setup your development environment. If not, follow the steps in Setup Dev Environment
# Checkout your local main branch
git checkout main
# Update your local main branch to mirror the main branch on Github
git pull
# Create a feature branch to work on. Name it something short and relevant
# to the change
git checkout -b add-patient-birth-sex After you've made the change you want on your local machine its time to commit that change to the project repo.
If you would like, you can prefix the commit message with an emoji code that is relevant to that change.
You can look up which emoji to use on the gitmoji website. Emoji commits can be useful when you want to quickly visually scan the commit history and get a quick idea of what kinds of commits a PR has (i.e. feature, bug, refactor, etc)
Here's an example commit message for adding something new:
# Stage the file(s) to commit
$ git add <file path to the file you want to commit>
# Commit the file(s) to the local repo
$ git commit -m ":sparkles: Add new birthSex extension to Patient" If another developer has merged their code (Pull Request) while you're working on your change, you will need to update your branch with those changes before you continue developing.
To do that, you will need to rebase your branch on the main branch like this:
# Checkout your local main branch
git checkout main
# Update your local main branch to mirror the main branch on Github
git pull
# Update your local branch with the changes on Github main branch
git checkout add-patient-birth-sex
git rebase main
# Push your updated branch to Github
git push -fIf you do this often you will rarely have conflicts.
Once you're happy with your changes, its time to open a Pull Request so that others can review your code and upon their approval you can merge your branch into the main branch.
Similar to commit messages, you can prefix the PR title with the appropriate emoji from Gitmoji.
For example:
✨ Add new birthSex field to Patient
When you open a pull request you will notice that the description is populated with a "Motivation" and "Approach" section. Please be sure to fill these out so that reviewers can quickly and easily understand the purpose of the PR and the changes.
Once your PR has been approved you're ready to merge it. Before you merge it, you'll want to "squash" all of your commits into 1 commit. This cleans up your branch's commit history and makes the main branch much cleaner as feature branches are merged into it.
This process is very easy to do because Github takes care of it for you. All you need to do is select the the "Merge pull request" drop down menu on your pull request page and press the button that says "Squash and merge".
Here's an example of what happens with squashing:
Branch Commits Before Squashing
The git log for this branch shows 5 seperate commits
$ git log
:sparkles: New birth sex extension
:recycle: Change data type
:recycle: Change values in ValueSet
:bug: Fix typo in ValueSet
:bug: Fix another typo in ValueSetBranch Commits After Squashing
Commits are combined into 1 new commit with a message that contains all individual commit messages to preserve history.
$ git log
Merge pull request #19 from ncpi/add-patient-birth-sex
:sparkles: New birth sex extension
:recycle: Change data type
:recycle: Change values in ValueSet
:bug: Fix typo in ValueSet
:bug: Fix another typo in ValueSetAs changes are made to the implementation guide (IG), we will want a way to track versions of the IG and tie those versions to snapshots of the project.
In this project we use Semantic Versioning to mint version numbers for various types of changes. Please read more at semvar.org.
Releases on Github are snapshots of the project at a particular point in time, stamped with a versionn number of some kind, in our case, semantic version number. A release can be made at any time, although, it is typical to make a release after a desired set of changes have been merged into the main branch.
To make a release you will need to install and run the D3b release maker CLI tool:
$ release buildThe build command will create a "Release Pull Request" on Github, which will have an updated Change Log of all the commit messages of the pull requests that were merged since the last release. It will also mint the next release version which is used to tag the main branch later.
When this PR is merged, the Github release workflow (already part of the repo) will tag the main branch with the release number, create a snapshot of the repo, create the Github release and attach the snapsot to the release.
The Github workflow will also publish the IG to its domain.
Let's solidify everything above with an example.
- Developer A wants to make a change to the code
- On their local machine, developer A checkouts a branch to make that change
- Developer B wants to make a change to a different part of the code
- On their local machine, developer B checkouts a branch to make their change
- Developer A makes the change and pushes the code to the remote repo on Github
- Developer A opens a Pull Request (PR) so that others can review the change
- Other developers approve the Pull Request
- Developer A squashes their branch's commits and merges the Pull Request into the main branch
- Developer B updates their local main branch with the changes that were just merged
- Developer B squashes their branch's commits and merges the Pull Request into the main branch
- Developer B opens a Pull Request (PR) so that others can review the change
- Other developers approve the Pull Request
- Developer C wants to make a release
- Developer C uses the D3b Release Maker to create a release PR on Github
- Other developers approve the Pull Request
- Developer C merges the release PR which activates a Github workflow that tags the main branch with the next version and creates the release on Github