Using a distributed version control system has been a fun learning experience, especially the collaborative nature surrounding open source project work. As I stumble upon more light bulb moments, I’m trying to make sure to jot them down here. One of them was the process for validating that someone’s pull request contains valid code by testing it before performing a merge. I figure there’s a couple ways to do this:
- Unit testing – See if the code itself is functional
- Integration testing – See if the code works against a running system and with other bits of code
- Ad-hoc (human) testing – Run the code manually to see if it works
- Eyeball testing – Read the code and look for obvious errors or conflicts
Each type of testing has its place. Eyeball testing, as an example, has worked fine for spelling and grammar changes. I don’t need to run those through a battery of tests.
It is important to test using whatever method is appropriate. Anything that enters the master branch should be production-ready code. If it’s not, put it in a feature branch (essentially any other branch). This, however, can be a challenge when accepting external pull requests because that person or persons may have no other choice but to issue a pull request against the master branch. They don’t have the permissions to create a new branch.
Testing Pull Requests against the Master Branch
At first, this stumped me a little. Until I realized that under each pull request existed a handy little command line link. It provides a simple process to follow for checking out the pull request code locally, testing it, and then deciding if a merge, new commits, or a conversation is required. You’ll find the link next to the Merge pull request button.
Here’s an example from the Rubrik PowerShell Module project. I’ve created a new feature branch in my personal chriswahl repository named Test and have requested that it be merged with the project’s Master branch.
By firing up the Git Shell on Windows, I can copy the instructions listed in Step 1 to begin the process. Here’s what happens:
git checkout -b chriswahl-Test master– This will create a new local branch namedchriswahl-Testand switch over to the new local branch in one command. The starting point will be the localmasterbranch.git pull https://github.com/chriswahl/PowerShell-Module.git Test– The code from the remoteTestbranch is brought into the local branch.
Testing the Changes
Now that the code exists locally, it’s possible to run the tests necessary to validate that the changes are good to go. It may be necessary to keep the changes in a feature branch for longer than this single commit before merging back into master, depending on what is being changed.
If your local repository’s branch is toast, you can always issue a git branch -D chriswahl-Test to nuke the branch and start over. Or, use a git reset to roll back any commits that have been made.
When changes are made, don’t forget to git commit them to the local branch before merging them back into master (or whatever branch you decide to use). They will be carried along when you execute Step 2.
Merging the Changes
When testing is complete, follow the Step 2 instructions.
git checkout master– Changes your local branch tomastergit merge --no-ff chriswahl-Test– Merges the changes fromchriswahl-Testintomasterusing the “no fast-forward” command (which forces a merge commit to be generated)git push origin master– Pushes the changes up tomasterin the GitHub repository (origin).
Automatically Closing and Tracking Issues
If there is an issue associated with the pull request, it’s also handy to comment that it has been fixed in the commit message or pull request comments. Using words like close, fix, and resolve will automatically close the associated issue. It’s pretty handy for linking together why something changed with how something changed.
For example, I received an issue in which a user wanted the date parameter to default to the current time if left empty. When I created the pull request with code that provided this functionality, I commented that the pull request “Fixed #19.” GitHub automatically linked to issue #19 (the one that requested the date/time feature). When the pull request was merged, it automatically closed the issue, too. Now, issue #19 and pull request #22 are linked together – I know why the code was changed, and how the code was changed. Truth in records!
The use of testing and in-depth history is part of why I really like working on public, open source projects. There’s a lot of experience to gain in learning better ways to collaborate with other PowerShell coders across the globe, and it’s enjoyable to work with a technology that enables me to do distributed coding. Enjoy!
