The great thing about GitHub is the way it brings developers together and promotes collaboration. In this example, I’m going to take a DSC module from Microsoft (xSQLServer), and combine it with some pull requests from Marko Bozikovic (@bozho). I’m then going to merge three of his pull requests so I can test 3 fixes that’s he’s contributed related to SSRS. Eventually, these will get merged into Microsoft’s code base, but I’m the impatient type and I want to use them now.
This is post assumes you’ve got some basic familiarity with Git, if not, check out my introductory articles starting here.
When you want to submit a fix for a repository you don’t own, you follow this workflow:
- fork (think ‘copy locally’) the remote repository
- switch to the branch that you want to write the fix for (e.g. ‘dev’)
- create a branch, by convention, this typically references the issue number & name, e.g. “issue-569-sql2016-virtual-dir-name”
- make your changes – you’ll likely have to update tests, amend documentation, and you’ll need to make sure you pass any automated checks.
- submit a pull request.
The pull request on GitHub includes a conversation thread where comments can be raised and addressed, see an example here.
Finally, someone with write access to repository will commit the change (in the case of xSQLServer, that’s going to be a Microsoft employee).
Clone and switch to dev branch
To begin, lets clone Microsoft’s repository, this is called ‘forking’.
- git clone https://github.com/PowerShell/xSQLServer .\xSQLServer
To switch to the development branch, run
- git checkout dev
Or within Visual Studio Code you can list & change branch like this:
Combining work from other branches
Now we want to bring in some code by someone else. We’ll start by adding a link to @boxho’s xSQLServer repository, that we’ll call ‘bozho’, and fetch it
- git remote add bozho https://github.com/bozho/xSQLServer
- git fetch bozho
This will pull in any new branches or tags created, in this case we’re interested in the fixes for issues 568,569 & 570
In order to test all three, we’ll create a branch and merge all three into it:
- git branch dev-ssrsfixes
- git checkout dev-ssrsfixes
- git merge bozho/issue-569-sql2016-virtual-dir-name bozho/issue-568-optional-sqlcredential bozho/issue-570-url-reservations
Git is smart about the way it merges changes and can often do them automatically, but occasionally it needs human intervention to resolve a merge conflict, as we see above.
In Visual Studio Code, click into the git workspace, and you can see the list of changes pending. “Merge changes” need intervention, “staged changes” have been managed OK.
If you click on “CHANGELOG.md” in the above example, you’ll be able to work through the file and make the necessary alterations, in this case, it’s a simple documentation change required to merge the list of ‘unreleased’ fixes
Make your changes, stage them (click the “+” next to the file), then supply a commit message as normal to save it to your local repository:
The ‘dev-ssrsfixes’ branch now contains a copy of Microsoft’s dev branch, combined with three fixes from another developer – we can now grab this DSC resource from Explorer and test it out.
- Copy the contents of your xSQLServer repository, excluding the ‘.git’ folder, to the target machine %programfiles%\WindowsPowerShell\Modules\xSQLServer\126.96.36.199\
Once testing is complete, you can remove your branch:
- git checkout dev
- git branch -D dev-ssrsfixes
& remove the remote from @boxho:
- git remote remove bozho
Keeping in step with remote repositories.
As time passes, and Microsoft push fixes to the xSQLServer repository, your cloned is going to get behind. To stay up to date, you’ll need to add a link to the remote repository, which we’ll call ‘upstream’
- cd .\xSQLServer
- git remote add upstream https://github.com/PowerShell/xSQLServer
- git fetch upstream
Finally, to commit code in your local repository, run:
- git pull upstream
e.g. if you’re working on the dev branch, it would be “git pull upstream dev”.
To update your remote repository (e.g. the copy on GitHub), run ‘git push’
- git push