Version Both Your Github Repo and Gem

There are many howtos on getting started with Github and creating a Ruby gem.  What I haven’t come across is a blog about versioning your github releases.  So I will demonstrate here the steps I go through after verifying a gem is ready, releasing it, and publishing a version to the code base on Github.

Test Before You Push

Before pushing up the gem you should test it locally.  If you’ve written a full test suite then that may well be enough.  But you may also have it tested within a local project.  When testing in a Rails project you can build the gem, install it locally, switch to the project directory, verify the version in the Gemfile, and then do bundle update my_project_name.

gem build my_project_name.gemspec
gem install my_project_name-0.0.1.gem
cd ../PROJECTFOLDER
edit Gemfile; echo "verify gem & version"
bundle update my_project_name
echo "enter command to run experiment environment and verify gem"

This is one of the way’s I’ve tested gems out, especially before I implemented test suites.  If you suspect your project may be using the wrong version of the gem then you can uninstall it with gem uninstall my_project_name and when it asks you which version just choose select all.  Then install the built gem in your gem project folder, go back to your project directory and run the bundle update my_project_name command again.  Rebuild the gem for each change in the gem code and repeat this process (unless of course you have a test suite written for it).  Note that we haven’t pushed the gem to the internet yet.  It’s important to verify it’s ready before sending it.

Before You Publish A Final Version

Once your code is working as you would like; take the time to update the Readme, Docs, and other information important for this release.  Verify the gem version has been updated to the next number in sequence based on Semantic Versioning.  Your gem version is specified through your gemspec file and normally points to your lib/my_project_name/version.rb path.  You can update it there.  Once your non-code updates are complete I’d advise you build the gem one last time and push it to rubygems.org gem push my_project_name-x.x.x.gem .

Version Your Git Release

Now you should already know how to push your github updates. e.g.

git add .
git commit -m "Epic! This is the gem version 0.0.1"
git push origin master

Now that your github is up to date and your gem has been pushed lets lock in a release version of the github repo that matches the gem version.  To create a version you need to add a tag to your repo and then push it to the server.  You can do so as follows.

git tag -a v0.0.1 -m 'Epic! This is the versioned tag for gem release 0.0.1'
git push origin v0.0.1

And now your github repo has a release count and you can select a tag to match each of your published gems for the project.  And I think that’s pretty nice.

Now it may very well be that you can combine the previous two steps into one commit.  But personally I really want to make sure that the pushed github code is what I want to lock into the version release before I push a tag up.  So in essence I have two repo pushes for the same content.  But at least I have peace of mind with it.

---

Update

As kwawer has pointed out to me in the comments you can use an included rake command to both create a tag for your git repo and publish the gem for you with rake release.  Type rake -T in your gem directory for a list of commands available to you with summaries.

rake release # Create tag v0.0.1 and build and push my_project_name-0.0.1.gem to Rubygems

---

 

Summary

It’s pretty simple once you learn about it.  From the majority of github projects I’ve seen though people aren’t versioning their github repo releases.  I think it’s only a matter of knowing how to do it and then each person will gladly do so.

I hope you found this information useful for you!  Please feel free to comment, share, subscribe to my RSS Feed, and follow me on twitter @6ftdan!

God Bless!
-Daniel P. Clark