How to Release a Github Project

Github.com is one of the modern concept in coding – the social coding. So using the site you can code socially – with friends, colleagues, mentors, even with someone you don’t even know. Most of the github projects are open source, because they are public by default. You can have private repositories also, but they are paid. Public or private – but most of the finished products hosted in github are not even released by their authors. Today we’re gonna take a look on how to release your github project.

Suppose your github.com repository is your project. And you are currently working on its version 1.0.0. Some other committers are also committing on the repository. And you all decided to finish its work for a stable 1.0.0 release. So, in that stage finish committing and go for a release.

Release using Git

The process of releasing product using git is actually git tag. Doing so you have to write in command line (git bash):

git tag -a v1.0.0 -m "First Release"

It will tag the last commit with v1.0.0 tag. Now push tags using command line and that will create a tag in Github too.

git push -u origin --tags

But it will write Release Note for you. So creating tags and release a product, Github has a feature called ‘Release’:

How to release

On your repository at https://github.com/username/repo click on the releases link.

Release link on Github.com

Click on the ‘releases’ link on github.com

On the Releases page, click on the Create a new Release button

Click on the 'Create a new release' button on the release screen

Click on the ‘Create a new release’ button on the release screen

On the release note screen fill up the release note.

Fill up the release note

Fill up the release note

The “Tag version” is the version number you want to release, for our scenario it’s 1.0.0. The “Release title” could be anything you want to entitle the release with. Suppose WordPress release its version with the name of a Jazz artist, so in your case it could be anything. We can say “First Release”, “Preliminary Release”, “International Release” etc.

In the description field with markdown, you can say a lot about the release. But a precise release note with some features would be great. You can see preview too.

If this is a pre-release, a release that is not official, but [quite a bit ready] for testing purpose or dev purpose etc. you can check the:

This is a pre-release checkbox.

You can save it as a draft or you can simply Publish the release with a single click. You can also edit and update your release any time. So, your repository/project is released now.

Version released on github

Version released on github

Attaching Binaries

What the binaries on a release note? If you are releasing something that needs an executable file, you can upload that here by simply dragging and dropping. Suppose you are releasing a simple PHP or HTML/CSS project, then you can simply compress the things in a common zip file then attach the file as a binary file.

Actually it’s the version of your project files that has no garbage code or file in it.

So, how to make a binary file. The type of your project actually dictates that. The process I like for scripting language project is, downloading the existing 1.0.0 release candidate version of the github repository as a zip file by simply clicking on the “Download Zip” on the right.

Download your repository as a zip file

Download your repository as a zip file

It will exclude all the git history, and will be minimum in file size. You can then additionally delete some other development related files or folders from the compressed file too.

So simply download the repository and upload the .zip file to your release as a binary file. We’ve edited our release:

Attaching binaries to github release

Attaching binaries to github release

For testing purpose, we’ve checked the Pre-release checkbox to declare it’s a pre-release.

Let's check how a pre-release can be

Let’s check how a pre-release can be

And we’ve attached our xyz.zip binary file, and we can easily distribute the path to the xyz.zip file to let the user download the product release. And that would be something like:

https://github.com/username/repo/releases/download/1.0.0/xyz.zip

Why binaries

Without the binaries anybody can download your released version by simply clicking on the “Source Code (zip)” file. But downloading that zip file will:

  • distribute unwanted bunch of your git revisions history to the end-user
  • not let you track download count of any project release

Yes, only a binary file can provide you the download count of a release.

Get download count

If you browse the API URL of that repository from your browser (just put your username and repository name) you will see the detail of your releases in JSON:

https://api.github.com/repos/[username]/[repo-name]/releases

And we know, using jQuery getJSON method, we can easily grab the download count of a release.

$.getJSON("https://api.github.com/repos/someone/kauwa-kala/releases").done(function (json) {
    var release = json[0];
    console.log(release);
    console.log(release.assets[0].download_count);
});

Conclusion

So, it’s easy releasing a version of your program, project, or repository, and even getting a download count per release. So, not just a git repository of code, let’s keep up releasing our product on github.com. 🙂

Comment here...