A Clean Contribution
Part of the process we have for contributing to Clarity assumes a basic knowledge of the git version control system and the typical pull request workflow. Consumers of Clarity sometimes give back and help us improve the components, the website or the documentation. We are infinitely grateful for any and all help. As a small dev team, the feedback coming in on multiple channels can sometimes be overwhelming. That’s why any pull request that follows the contribution guidelines and fixes or improves the components and docs is an enormous help to the project.
The contribution process is pretty simple unless you are implementing a new component from scratch or making big changes to an existing component.
- The contributor forks the Clarity repo and makes a branch for their changes.
2. Once they are satisfied with their changes, they submit a pull request (PR).
3. Team members review the PR and sometimes request changes.
4. The external contributor addresses the changes by adding a commit to their branch.
5. Once everyone is happy, we ask the contributor to squash all of the commits in the PR branch and craft a nice commit message.
It's these last few steps that can create more work for contributors and block them from contributing.
DCO Signature
We require that contributors acknowledge and adhere to the Developer Certificate of Origin for VMware by signing their commit:
git commit -s "NAME SURNAME <email>"Squashing and Rebasing
Once a review is complete and there are no more changes to the pull request, we need the contributor to rebase the branch and squash all of the commits so it can be cleanly merged into the master branch.
What sometimes happens is that one or more changes during the review process get committed without the signature and the PR gets blocked by the DCO bot. After the contributor has squashed and force-pushed the single commit that fixes or improves Clarity, the commit they squashed somehow isn’t signed and the PR gets blocked by the bot that checks for a DCO. What often happens is that the external contributor will close the PR and open a new one that we have to review from the beginning, again.
There is no need for that! This could easily be fixed with git! It is easy to amend a commit and sign it.
git commit --amend --author "NAME SURNAME <email>"You need to be aware that when you use the amend and author commands ––just like with rebase — you are rewriting history and will need to force push the new history to your branch. That's why we ask you to squash the PR history at the end, once the review process is complete. It saves us from re-reviewing all of the code changes over and over.
I know it can be confusing and seem like a lot of work — especially if signing git commits or rebasing the history isn’t something that you do routinely. But, like everything else, the more you practice, the easier it gets.
Here is a handy guide to working with git commits in a pull request branch.
Sign It
Sign and commit all requested changes sequentially as the PR gets reviewed with this handy git command: git commit -s “NAME SURNAME <email>”. In fact, there is no reason why you couldn’t sign all of your commits like this.
Squash It
Squash the history of your contribution into a single commit. This command will open an editor that you can use to create a clean and descriptive commit message: git rebase -i HEAD~n (where n is the number of commits you made on your pull request branch)
Fix It
Fix any DCO signing issues for the last commit by amending and force pushing the offending commit: git commit — amend — author “NAME SURNAME <email>” and then git push -f. Be aware that force pushing will rewrite the git history on the branch you are pushing to.
That's All Folks
By following these tips you will have an easier time getting a PR accepted and merged into the project. It also has the benefit of keeping the history clean and understandable. Hopefully, these three things will make it easier to finish off your pull request and cleanly get your contribution merged into the project.
