How can I look at a GitHub repository and know what version of the code to download?

Question

I am new to GitHub and new to the open source world (coming from .NET). I have a media wiki site and want to install a Google analytics extension: http://www.mediawiki.org/wiki/Extension:Google_Analytics_Integration

The extension's documentation says to download the code from GitHub.

In the GitHub repo, there are some "reviews" that say master and some that that say branches. I assume that I want a master and not a branch. But how do I pick which master to download? Also, the documentation says that some of the commits will be tagged but this does not seem to be the case. Without tags/documentation is there any easy way to know what commits are stable and what commits are not?

I'd love some general wisdom about how to approach a repo for a project like this.

Answer 1

If the repository is following the usual patterns (which is slightly more likely for Git repos than other VCS, in my experience) then you want the master branch for stable releases. In theory, if it's in master then it should be tested and working, so the most recent commit to master should be the most recent stable release.

Looking at the repo you linked, I go straight to the "branches" section, and see "master". Clicking on that, I see that this commit is tagged REL1_21, which I assume means release 1.21, which I'm guessing corresponds to the name for this version used within their documentation. That's a good place to start.

Quickly scanning up from there, I see mostly commits by a bot, updating localisation. Probably nothing breaking in there. There's also one commit that mentions a change. If they're doing things properly, this should be a fix, and definitely not a breaking change, because it's a commit to master without a version tag. Checking the comment on this commit, I see that it mentions steps taken to preserve backwards compatibility.

Now that I'm happy that nothing bad has been pushed to master since the last release, I simply grab the latest commit: at time of writing, that's this one. If I have problems with this version, or if I wasn't convinced that the change was safe, I'd get the last tagged commit, and stick with it until they add a version to master tagged with something higher than 1.21, (which, based on a quick guess at their versioning system, would be either REL1_22 or REL2_0).

Of course, one would hope that the project's documentation would point you to the correct version, rendering this process of figuring it out yourself unnecessary, but sadly that isn't always the case. When you find yourself in this situation, the process I used here works for most repositories, Git or otherwise, provided a vaguely sensible branching strategy has been used:

• Find a branch called "main", "master", "stable" or something similar
• Find the last version-tagged commit to that branch
• Check nothing odd has been added to that branch - anything that might introduce breaking changes
  • If there's nothing, grab the latest commit
  • If there is a potentially problematic change, grab the tagged commit
• Either way, if you have problems with the version you have, move back to the previous tagged commit.
• When you find a version that works, stick with it until they release a new tagged version, then get that. If it doesn't work, move back to the one you were on before and wait for a new version.

Answer 2

In a git repository it is mostly very easy to find that out. There will be different branches and master is just one branch of the branches. In tradition you will find on master the stable/approved/current (depends on branch handling) versions. Some people just develop with master.

If such a repository is hosted on Github (the linked is not), you can see the tags fairly easy. The linked repository seems to put the most recent version on the master branch. You should simply use the latest available commit.

What version you should download depends hugely on how the project is maintained. As an example for a Github repository here the Symfony2 Github repository.