It's extensive, clear, and, of course, searchable.
Sorry, there is no results for this query
Here I’ll share a few things I’ve learned managing libraries at Algolia. They are by no means a perfect set of instructions or recommendations, but tips for making your (developer) life easier.
Here are some good signs that you may want to re-work your release workflow:
The team’s action plan was to:
The first step was easy to do given we had used Git as the source control system for the project. We just had to revert some of the latest commits. For the second point though, the procedure included many steps.
Even though having a lot of steps is not a problem in its own right, what was a problem is that a lot of questions came up:
Even if I was asking myself only one of the above questions, I would have started doubting myself and feeling uncomfortable about the entire process. Asking myself all four was…too much.
I learned two things that day:
To make sure a fair amount of engineers in your company can deploy a project, the best solution I can think of is a single bash script which would guide them through the publishing steps.
Some companies like Etsy take this quite seriously and have their new employees release something to production from day one in the company
Next time you publish a project, here are a couple of questions you could ask yourself to evaluate the quality of your release workflow:
I recommend automating the entire release process as much as possible, which includes taking care of those tiny little things you think are not worth automating.
For example, you should not have to replace the version number in any file manually, the reason being that one day you will forget about replacing one version number, or one day it won’t be you releasing. That day, you will probably lose a lot of time and possibly negatively impact production environments. Furthermore, chances are that the time you will lose that day is more than the time it takes to automate your release process today.
A good practice is to aim for a single command line you can execute to get your software released. Ideally the command should be interactive and guide you in the process by asking some questions like::
Here’s an example including some of those questions:
In almost every project I work on, there is some kind of a continuous integration setup.
On every new commit pushed to the repository under source control, all tests are run in a single environment or in multiple ones. This has the advantage of making sure future releases are working correctly on the targeted platforms, but has the drawback of slowing down the time needed for the release to get out.
Because implementing pragmatic releasing is an iterative process, some projects I’m working on are still taking up to 45 minutes to have all tests pass. This mainly happens when the project has many integrations and end-to-end tests including relying on calls to an external API, Algolia in my case.
Having long running tests like these can be a real bottleneck for productivity. I would personally tend to avoid having to add features to those projects, because I know it is going to be time consuming.
Just to give you an idea, here is what the process of adding a single feature to such a repository looks like:
In a best-case scenario, it takes about an hour to release even the simplest possible feature. If you are unlucky, though, you could spend a day working on getting a feature out. Now imagine this feature is an actual bug fix impacting production environments. It would be totally unacceptable to have to wait one full day to get the patch out.
Ideally, the time to release a new version should be equivalent to the time to implement the feature and get it reviewed. A few ways to help accomplish this:
Whatever the issue might be, taking some time to speed up to release cycle is key to fast iterations.
In the previous paragraph, I shared how much I think speed of releasing is important for a project. One thing that is equally important is the quality of the builds you are shipping.
The moment you get something released, you have to be confident it achieves what it was designed for. In other words, you should test your code to ensure business expectations are met. There should be no way to release a project that has failing tests.
However, I think that it is also perfectly fine to ship a “work in progress” feature as long as it doesn’t impact other features. If you have a chance to break down a big feature into many smaller ones, you’ll be able to iterate faster because the review will be easier.
Next time you are about to release your library, ask a colleague who knows nothing about your project to deploy it. Give them the URL of your repository as the only instruction. If they succeed in releasing, it probably means the quality of your release cycle is not bad.
Next time you have an incoming task that is easy to address, get it done right away and force yourself to release the change. If you feel like you would have preferred to open an issue and deal with it later instead, it probably means you can still optimize your release workflow.
When you reach the stage where you can release on demand, you address issues differently. Instead of polluting the repository with issues that would distress and distract you, you get things done instead. Plus, given other teammates are able to release the project without your help, you can live without the fear of having to remotely guide a stressed out coworker on your day off.
When you have a robust and simple release script, you can release when you see fit. The mental gap between release intention and the actual release should be negligible.
In the “Don’t rely on a single person to release” section, I shared a real story about a project that impacted real production environments. Between the initial report and the actual fixed release we lost about an hour of time. By implementing a release process that follows the principles shared here, the time to release the bug fix is now equal to the time necessary to implement the bug fix. In most cases, this would be a couple of minutes if you are using a source control system like Git: just the time to revert the changes and release again.
Here’s how I like to design the release workflow as of today:
Conventional commits dictates a format which every single commit of your repository should follow. By doing so, you’ll be able to:
I would recommend you use conventional commits to avoid the burden of manually having to update the CHANGELOG file.
I would also suggest you have your CI platform test all commits to ensure a badly formatted commit cannot be committed to your master branch. You could use something like commitlint to ensure the format is correct.
Create a script (in bash for example) that will do the following:
Here is an example of such a bash releasing script:
Create a script (in bash for example) that will do the following:
Here is an example of such a bash publishing script:
Previous step assumes you manually check out the changes after you have merged the release branch, and then run the publishing script. You could also let your CI platform handle this publishing for you every time something gets merged into your master branch. Personally, I like to keep this publishing task manual, because if something goes wrong, you are able to fix it easily.
Releasing software should be something you enjoy doing: each time you release, you either fix a bug or introduce awesome new features. Spending some time to optimize your release workflow helps delivering better quality faster.
I would love to hear what you do to make your release flow less stressful and more fun: @rayrutjes.