The Surly Admin

A Practical Guide to GitHub for the PowerShell Scripter

When I first started dipping my fingers into the GitHub pool, it was because I really felt there was a need.  Version control was becoming an issue and having to re-write code I’d already perfected because of a glitch somewhere on the way–translation: accidentally deleting the wrong file–was something that just had to be addressed.  And, I think like a lot of PowerShell scripters, I soon started asking questions like:  WTF is this?  What is going on?  Who came up with this crap?  I’m no expert, but read on if you’re interested in learning how to use PowerShell and GitHub together.

Overview of Git

This is going to be a really high level overview.  Most documentation I’ve found for Git gets mired in all the different command line options and I don’t want to do that, just function on the mechanics.  Interested in the history?  Check out Wikipedia for that.

The first thing to remember about Git is this was meant for developers and its features and functionality are designed around their needs.  So there’s some big capabilities here, things that the average scripter doesn’t really need to worry about.  At the very base is the “master” repository.  This is the gold code, this is the code that’s running on your server right now.  Ideally this code is treated with the highest level of respect and only modified when absolutely ready.  Next comes the idea of the branch, this is a copy of the master and is meant as the jumping off point for code changes.  Notice we don’t make code changes at the master repo level!  A branch could be a new version, a monthly/quarterly build, maybe a major feature enhancement.  Now is when the different developers step in.  As a developer you’ve been tasked to write “Feature X” into the product and to do it in “Build 1”, so you go to that branch and you “Fork” it.  This makes a copy of the branch in your personal repository.  Next you would clone your personal repository down to your computer and begin coding.  Code changes live in your clone and require two steps to make it back to your personal repository.  First you have to “Commit” the code which bundles all of your changes into a single grouping, then you “sync” your clone which will then copy the data back up to the Git server into your personal repository.  You would do this periodically during your code process to make sure you had a copy of your work on your repository.

Days, weeks, months later “Feature X” is completed.  You’ve tested it a thousand ways to Sunday and you are confident that it’s good to go.  At this point you would issue a “Pull Request” back to Build 1. The architect (or owner) of the Build would take a look at your request and approve it, or make comments in the pull request about things you forgot or missed or screwed up.  You would make changes to your code, commit and sync again and those changes would automatically become part of the pull request.  After a nice discussion the owner would merge your pull request and voila you’re code is now part of Build 1.  Keep in mind that the owner could easily be dealing with dozens of developers all working on their own projects and pulling their code into Build 1.  But at some point all the pull requests have been made and the code is ready.  The owner of Build 1 would then issue his own pull request to the master repo.  The owner of master would then make her reviews, comments and so on and when the code was considered production worthy she would merge the pull into master and the process is completed.  At this point, all the changes that were developed for Build 1 are now part of master.

Keep in mind that parallel builds can also be going on, so Build 1 might be dealing with hotfixes, patches, security issues and so on while Build 2 is working on feature requests and Build 3 is working on new functionality.  One scenario, at this point, would be to delete Build 1 and create Build 4 and you might get reassigned to that build, or reassigned to one of the other in-flight builds.

That’s just one example, of how it’s done.  Maybe there would be permanent branches called “Hotfixes” and another called “Feature Requests” and another called “New Version” and things just continually get developed there.  It’s all very flexible.

PowerShell and Git

Now that we have a basic understanding of Git and its ways, how do we apply that to a simple PowerShell script?  The simplest way–and most common–is what I call the Master/Clone method.  You create a Master repo, clone it to your PC and get to work.  When you have some code you’re happy with you commit and sync directly to the master repo and you’re done.  This is certainly easy but you can’t really commit your code while you’re working on it since it will be part of the master the second you do and someone might download some incomplete code.  Since you don’t have a backup of your code on GitHub, dropping your laptop into a puddle becomes a real problem, too!

A slightly better approach would be the Master/Fork/Clone method which is much like the Master/Clone method, but you would fork the master to your own personal repository then clone that fork and develop there.  When all your changes are ready to go into production you would issue a pull request directly to the master repository.  This has the advantage of allowing you to commit/sync your code often and review it before you finally put it into production.  Also, if you decide to start to use the continuous integration features GitHub has (full Pester testing right in GitHub!) the pull request is where that capability is triggered.  For both techniques, outside contributors would fork the master and issue pull requests to have their code considered for integration into the master.

Master-Dev Approach

My personal favorite is the Master-Dev approach.  This has a master repository, and a “Dev” branch.  The dev branch is cloned for the owner of the project so they are directly in charge of it, while contributors would fork the dev branch and issue pull requests to get their code into dev.  Once all development hits a certain point–as determined by the owner–a pull request would be issued from dev into master.  This supplies the owner with the most flexibility and allows code to be reviewed and tested at all levels before the final pull request is made from dev to master.

This is especially good for the owner if the project is a module as any changes to the module or manifest files can be made by them without having to rely on the contributor to do it right–translate: the way you want it done.

A Quick How-To

Let me show you the fastest way to setup the Master-Dev approach:

1. Create a new Repository from the GitHub website.  Select your license (I like MIT, but pick what you want).
2. Branch the master and name it.  I like “dev” but use whatever you want.
3. Open the GitHub for Windows client on your PC and clone your new repository
4. When it’s clone, make sure you have the dev branch selected.
5. Dump your code into the folder and you’ll see the Changes section with everything you put in there.
6. Commit the code and hit Sync.  Everything will now copy up to the dev branch.  You can actually flip between dev and master and see that master is still empty.
7. From the dev branch on the GitHub website, click on “Compare and Issue Pull Request” and finish the dialog box
8. After the pull request is issued you’ll see a button for merging which you can then do
9. master repo will now have your gold code in it ready to go.
10. Continue developing and committing to the dev branch and doing pull requests only when you code is ready to go.

Contributing

I really encourage you to create a CONTRIBUTING.MD file in your repository.  This file is a simple text file where you can issue instructions to outside contributors about how to write their code, where to fork (dev, not master!) and other general guidelines for making contributions to your project.  Any file in GitHub with an MD extension is considered a markdown file so you can use that for making a more generally appealing looking document.

February 22, 2016 - Posted by Martin9700 | PowerShell, Technical | commit, GitHub, PowerShell, pull request, repository