Collaborating with multiple authors with GitHub

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.

Workflow recap

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’.

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

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\7.1.0.0\

Tidy up

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’

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

Version Control for IT Pros

In this series, I’m going to write about using PowerShell with Visual Studio Code (“VS Code”) on Windows.  If you’re on Mac or Linux, don’t feel left out, VS Code & Git are available on these platforms too, and it is an excellent editor for many languages, so if version control is new to you too, why not follow along as well?

Version control of scripts, software code, or other text-based assets such as websites is an important safety net, it’s ubiquitously used by programmers, where its value as a record of change and as a collaboration tool is accepted & well understood.

I’ve met many IT pros are either unaware or choose not to use version control. If minor changes are required, they might be made ad-hoc by editing files directly. If it’s an important script or a significant change, the old version might be renamed or placed elsewhere. Folders might get cluttered with old versions, or it might be hard to identify the right version. Change might well be recorded somewhere (inside some ITSM tool, perhaps), but typically it is hard to get a detailed line-by-line record of how a particular file has evolved over time, and who might have made those changes.

Good version control becomes even more critical when you start to break your scripts into shareable modules, since changes to a module upon which others depend may have significant consequences. Generally, as IT pros become more dependent on automation and scripting, managing these resources becomes increasingly important.

Visual Studio Code, a great IDE for coders, web developers & IT Pros.

Visual Studio Code is a relatively new free & open-source IDE from Microsoft, more feature rich than a basic text editor, but much lighter than the developer-centric Visual Studio. The download for VS Code is pretty small at around 34MB.

The IDE was originally developed as a cross-platform editor for the TypeScript language, and it has an extremely rich extension system, one of which is for PowerShell (it has heaps more). This PowerShell extension is, in many ways, more flexible than PowerShell’s baked-in ISE. It has matured very well in recent months, filling in functional gaps found in earlier versions.

There are many benefits to using this IDE above the basic PowerShell ISE, but in this article, we’ll focus on version control integration using Git.

Did you just call me a Git?

Git is a free & open-source distributed version control system for text files (mostly).

It is ‘distributed‘, because, everyone who works on the code has a full copy of the current files and all version history. This sounds quite inefficient, but there are huge projects using this mechanism and it scales surprisingly well. The distributed nature it means you’re not completely dependent on the availability of a centralised repository.  Since you can work completely offline, you can carry on hacking on your multi-million-dollar idea when stranded on a desert island, at least until the battery runs out.

The version control’ provides a way to track changes within a folder hierarchy. These changes & their meta-data are all self-contained in a .git folder at the root of the folder being managed (the .git folder should never be interfered with).

Each top-level folder to be managed is called a repository, typically a repository holds the code for a particular project or set of related activities. Since all the version information is self-contained, these repositories are completely portable – they can be moved around or stored in different places on different workstations.

One of the most exciting parts about Git is the development of social-media-style websites, where developers & IT pros can co-author code, collaborate, track issues in a very open and transparent way. You’re probably already heard of GitHub, or at least come across it – it’s where the brave new Microsoft open-source their software, including, for example, PowerShell, ASP.Net Core & Visual Studio Code. Repositories stored on another system are called remote repositories, or just ‘remotes‘.

I’m going to use GitLab to illustrate hosting a remote repository, which is very similar. GitLab provides free repositories that can be made ‘private’ to a group of individuals, which is a paid-for service on GitHub.

  • If your company is already using a private Git repository, you’ll need to request access from your organisational admins. They will typically send an invite to your company e-mail address, with instructions to follow.
  • If not, you can follow along by signing up, and you can use my repository.

The skills you learn here are directly transferrable to GitHub – I use both simultaneously, GitHub for personal projects that I open source, GitLab for my work, and Visual Studio Code switches between GitHub and GitLab seamlessly, as I move between different projects.

Let’s get installing

Let’s get some software installed, we’ll make this quick to avoid boring the *nix people. I assume you’re using chocolatey (if you’re not, you should install it). The following will install git + visual studio code along with a couple optional-but-highly-recommended utilities (PowerShell for Git aka ‘poshgit’, and a helper to cache login details for GitHub and GitLab in the Windows credential store)

choco install git.install -y

choco install git-credential-winstore -y

choco install poshgit -y

choco install visualstudiocode -y

OK, so, now you’ve finished chuckling about being a ‘poshgit’, and have software installed, let’s move on!

Identify yourself

Before we can start using Git, we need to identify ourselves, we’ll do this being using the Git command line tool, before switching to Visual Studio Code:

Find Git CMD:

Configure it using the name and e-mail that you signed up for with GitLab

git config –global user.name “My Name”

git config –global user.email “my@email.com”

Create an empty folder to store the repositories, it should be a local directory on your computer. I typically go for something short like C:\Work to avoid typing too much, if you’re on *nix then stick it somewhere easy like ~/work.

Remember, this repository will be stored in GitHub, so as long as you synchronise reasonable frequently that should protect you from lost work.

Clone your first repository

When you want to work on an existing repository, you clone it. This takes a copy of the remote repository and copies it to your machine.

To do this, you need the repository URL, in the case of GitHub or Git Lab, this is the same as the website address for the repository.

I’ll be illustrating this using the repository here: https://gitlab.com/kewalaka/vscode-training.  This contains a small collection of simple Powershell scripts.

On the home page for VS Code, select “Clone Git repository”

If you’ve closed the Welcome page, you can get to it from the Help menu -> Welcome.

Enter the Repository URL:

Chose the parent folder (note, it will create a subfolder with the name of the repository)

Select “Open Repository”

The contents of this GitLab repository will be saved to your file system, and you can see them in the tree view on the left of the IDE.

If you’re the curious sort, you can confirm the presence of the repository by looking inside the hidden ‘.git’ folder:

Creating a brand-new repository

Let’s say you’re starting a new project ad there’s no existing repository. The easy way to do this is to first create the project on GitLab, here: https://gitlab.com/projects/new

  • Enter the project name.
  • Enter a description
  • Choose the visibility level. Note that “Internal” means that any user with an account on GitLab will be able to clone this repository.

Having created the project, you can then clone it from Visual Studio Code using the same mechanism above.

Branching out – keeping your production code safe

Central to Git is the idea of ‘branching’, this is typically combined with a workflow that allows collaboration on independent issues and features, whilst reducing the risk of changes to production.

The workflow possible is as complex as your organisation can imagine, but one approach looks like this (also illustrated below):

  • There are three branches – master, hotfixes and development
  • New code is developed and tested in the ‘development’ branch
  • Once signed off, it is merged to the master branch, which is for production ready code
  • For larger projects, specific releases are typically ‘tagged’, this allows the team to identify the code that belongs to a specific version of software.
  • If a production issue arises midway during development, the hotfix branch is used to clone production and a patch is created and pushed to both the master & development branches.

By default, if you don’t branch, you’ll edit the master branch directly. This might be OK for very small projects, or if you’re just starting out. Even if you’re just working on a folder library of scripts, wouldn’t it be great to know which are production ready, whilst allowing work to be done in development to improve them? Always treating the master branch as production ready makes that possible.

You can create a new branch or switch to an existing one in Visual Studio code by using the command bar (Ctrl+Shift+P), and typing git checkout branch-name

If the branch doesn’t exist, it will be created in your local git repository.

Don’t worry if you’re not quite following this, we’ll pick up branching in the next post.

What’s next?

So, you’ve begun the journey towards protecting your precious scripts using version control. In the next post, we’ll look at how to start making changes using the above workflow.