In this article, I would like to share my tips on how to improve your Github repository so basically, how to give it some ‘steroids’. I will cover aspects like using templates, coverage report in Github projects and packages, how to improve the CI build speed and finally, how to better document your code.
In the past, in the company I work in, we had a tool that allowed giving feedback to people and the code they write. Later on, the process was automated since everybody saw that the tool was redundant in most cases and could easily be replaced. This is the reason why I’m writing this article, to prove that some recurring tasks that we do on a day to day basis can be automated, especially on Github.
Table of Contents
Templates
The first example can be PR templates. You may ask, what does that give me? Well, using templates for PR creation on Github is not only documenting your work and what is your code about, but also is clearly showing that your comprehension of the feature is aligned with the customer requirements to those, who are looking at your pull request.
It also makes it much easier to get the important information required for quality assurance for people reviewing your code, since it is all in one place. What is more, it is easier to perform tests if you explicitly describe the necessary steps by providing a testing scenario.
Pull request template sample
Do not forget that templates allow attaching even video previews that can help your QA team member see how the product you are working on performs saving the time of both you and your client.
Most recently, Github allowed creating templates for each type of issue that is created in your repository, which comes in handy especially for open source where the maintenance has to have some framework or template for issues to avoid repeating questions like ‘Can you give me some context of this issue?’. With templates, you are putting everything inside the issue template and when someone wants to create an issue he has to fill out the template answering some questions. This simple solution brings order into your repository.
Coverage
When it comes to coverage, do any of you check spec coverage of your builds regularly? Previously, we were using Cane gem, which automatically checked that, so combined with Simplecov, at least in Ruby projects, you knew whether or not your spec coverage is lower than for example 90%, however, that was the most useful for statistical purposes. There are better applications available on Github marketplace (for instance: CodeCov that have much better report features like reports even for the new changes that were introduced to your project, so in each iteration, you can see which file was not covered since the reports do that for you.
Updates
Another tool worth considering is Greenkeeper, which deals with updates on your project. We often have to remember about keeping everything as fresh as possible and we usually do that manually, but no more. Once the tool is linked to your Github repository it will automatically create pull requests on each update of the packages that you are using. What is great about this solution is that if you have good tests or specs coverage then it will do checks for you, so once the version of your packages is automatically bumped and you trust your specs, you have ready-to-merge pull request.
Pull request sample created by Greenkeeper bot
CI Speed
Let’s talk about speed for a second. Not so long ago, we had a project where our build took about an hour, which was very frustrating. I asked around in my company and came out with a solution called Knapsack gem, which splits your build into two or more separate builds, which shortens the time of your builds.
Changelog
OK, but what about changes in our repository? What we have to remember about is to follow some kind of rules to make the changes tool truly useful. We shouldn’t create misleading pull request names. All you have to do is use a gem called github-changelog-generator which will regenerate your changelog based on the pull requests you merged, issues and releases. We run just one command and the complete change log is rebuilt. There also is an alternative to this method Lerna-changelog which based on your labels. It adds fancy icons to your changelog as well as stats who are the committers at the end. It is super useful if you are maintaining open source libraries.
Changelog sample from Lerna
Documentation
Moving on to the final concern of this article — documentation of the code. I know it is not the most fun thing to do, but in terms of libraries, it is necessary. Thanks to inch-ci.org you can get a badge that tells you what is the coverage of your library in terms of documentation. It can also give you pretty nice suggestions (similar to what linters do) and I highly recommend using it, especially in libraries.
Bonus: video & slides
Take a look at slides and the video from my presentation (@ Selleo Haxorz July 2018 event):
Conclusion
The whole point of this article was to show that our repositories are like products and we should treat the people who visit them as potential customers. We should focus on delivering cool stuff, great features, not only focus on tasks that are repetitive in our repo. So please, do not waste your time and automate things that you can automate. If I had to choose the most important thing of the whole, personally, I would say templates are a must for me.
For the last and final sentence of this article, I would like to add that none of the above-presented tools are expensive in use. I mean, what is a couple of dollars (monthly) if you can make your life easier with automation tools, right?
Feel free to share your thoughts in the comments below, follow me on Medium, subscribe on YouTube and don’t forget to spread the word.
