Now that we’ve created the GitHub Repository for the PMDK, here’s a more detailed description of the git workflow we’ve chosen. The basic idea is:
stable-1.xbranch is created. All bug fixes should be committed to the oldest affected branch which is currently supported. Stable branches will be merged periodically to later branches and master.
Here’s a walk-through of the common development workflow, where changes
end up on the
As shown in the above picture, the
master branch moves forward in
time, collecting commits (shown as the small circles) and periodically
tagging releases. In the above example, one user has forked the
repo and has created
feature-branch-A locally to work on a change.
At the same time, another user has forked the repo to work on
feature-branch-B locally. Forking and creating a local feature
branch are the first steps in development and are done like this:
upstreamto point to the original repo:
Now that you have your local feature branch, do your development with frequent commits recommended. Be sure git is configured with your correct name and email address:
Now you can work on your changes locally, committing them to your local feature branch:
Please follow the common conventions for git commit messages:
For example, here is a properly-formatted commit message:
At convenient points in your development, you will want to re-sync with
any changes that have happened in the upstream repo. Do this using
git rebase rather than
Before asking for your changes to be merged, you are expected to perform these steps at a minimum:
We also require all the above to pass using the
Please add the appropriate unit tests to verify new features you’ve added.
Please note that the C++ compiler must support the C++11 standard.
If you’d had a good number of uninteresting commits, such as
those that fix typos or head down a wrong path that you later discarded,
you should consider
squashing those commits into a cleaner set of commits. The command
git rebase -i is a very useful tool for this. For example:
The above rebase command will put you in the editor with a list of all the commits you made on your feature branch. This is a very powerful operation with lots of possibilities – too many to describe here, but a quick remind may help you use it. Say you had four commits but two of them were annoying typo changes that you’d rather just squash away. You’ll see the four commits in the edit like this:
Let’s say you want to convert this to two commits, folding the typo fixes into the commits before them. Change the word pick to squash for the commits being squashed – actually, you only need the letter s, like this:
When you write and exit the editor, git will allow you to edit and clean up the commit messages for each set of squashed commits (twice in this example).
Note: if you haven’t used rebase -i before, you should make a copy of your repo before doing this, just in case!
Now that you’ve your changes are cleanup and fully tested, you’ll want to push them back to your fork of the repo on GitHub:
And finally, send the changes back to the original PMDK repository:
git rebase -i). When you try again to push your changes you may encounter git error “failed to push”. In such case it’s required to use “–force” option (
git push -f origin ...).