Hanami Release Management

proposals
1

Our release management follows one rule: it’s ready when it’s ready, and when it’s ready we ship it.
Simple enough have me as the main maintainer for Hanami until now.

With the new people joining the team, and perhaps new collaborators, we want to coordinate the effort between us.

What worked so far…

The current model worked fine because in a pre-1.0 era, you’re in a discover phase, and it’s hard to predict when the building blocks of a framework are ready.

However, the lack of time-boxing had a few downsides.

Contributors who promised to deliver a feature, after they opened the draft PR, they disappeared. Large components never get right at the first cycle, they need to be polished, documented, tested in real projects. Opening a PR and leaving it, it’s like never working on it in the first place. Again, I believe that the lack of a date for the release may have removed the sane pressure to actually finalise features.

The other problem that we faced is to not give in developers’ hands a preview of a major feature. Releasing a feature after right it has been merged it’s not good for the stability a release.

What we can do? I think we should introduce a few basic rules:

  • Still follow Semantic Versioning 2.0

  • For a feature we should have an owner and a backup: in case the owner can’t finish it, the backup can take over the leadership. The two people must communicate over time. As soon one of them cannot continue to work on the feature, they must communicate to the core team.

  • Agree on a date when the feature should be ready to be merged. That implies that the PR should be opened largely in advance (a month is ideal). So we can have time to iterate, polish, document.

  • We won’t to jump straight to a stable release, but go through the alpha/beta/rc (aka pre-release) cycle.

  • After we merged one or more features, we should be able to craft a pre-release, so developers can try it and report bugs.

  • New APIs must be tagged with the YARD annotation: @api unstable.

  • We should be able to release a patch version for bug and security fixes anytime.

  • Since 1.0, master will become the branch that is always ready to be shipped for bug/security fixes. New features must use develop branch as target for PRs.

We should decide one of the following release models:

It’s ready when it’s ready

We can keep this current model of release by adopting the rules described above.

We should evaluate from release to release the coordination between features and how to put them in developer’s hands as soon as we can.

Fixed Release Cycle

Before a stable release is out we decide which features to implement for the next cycle. For instance, before 1.0, we should decide what goes in 1.1 and who’s gonna be responsible for each feature.

Starting from the stable release, we target the next stable release to happen 6 months later.

The first 4 months are to develop the new features, while the remaining 2 months are for the pre-release cycle.

If a feature takes less time, the person can decide to take another feature.

If a feature takes more time, we should still merge it, but make it not part of the public api (hence the @api unstable).

This 6 months cycle is for new features, bug/security fixes should be released as soon as we can. These small releases must be patch releases. Eg. 1.0.1.

That means each 6 months we will bump a minor or major version: it could be 1.1, 1.2… or we can decide to go for 2.0.

This model has the implicit advantages of the time constraint and the coordination between features.

Please suggest improvements.

:cherry_blossom:

3 Likes
2

This is a great idea, Luca.

For a feature we should have an owner and a backup: in case the owner can’t finish it, the backup can take over the leadership. The two people must communicate over time. As soon one of them cannot continue to work on the feature, they must communicate to the core team.

How are we going to assign backups? It seems unreasonable to ask people developing a feature to find one themselves. Some people in the Hanami community know each other (which is great, and we should encourage this) but others don’t know anyone else. It seems like an odd thing to ask possible contributors to seek out a stranger to help them in case they can’t finish. Maybe we can reach out to people in the community and see if they’d be billing to be backups? Else, we could just assign someone from the core team to be the backup?

Since 1.0, master will become the branch that is always ready to be shipped for bug/security fixes. New features must use develop branch as target for PRs.

I like this approach, and this is what I do when developing apps.
Can we set ‘develop’ to be the default branch for all the repos? Changing the default branch - GitHub Docs I feel like having to rely on people manually switching the branch themselves (or having us do it) would be a pain. Note: this also means that develop will show up by default on the web interface, which is fine, I think.

-sean

3

That in itself is a good question.

I have a kinda of bad idea: let’s say that we have some place to list all the features we intend to work with. With that in place we could only start it when someone agrees to be the backup. An issue/feature without a backer probably is either too complex, too specific, no one has the time to look after it or lacks general interest, maybe even more than one of these.

What kinda makes me worry is the number of features a single person might end responsible for. If I’m the backup for 3 features and I’m already working on one, that could compromise all 4 of those at the worst case.

4

We can agree with contributors from case to case. But yes, to fallback to core team for this is good.

I’d say not yet. develop branch should be use to develop new features, if we have a contributor that wants to work on something, we’ll agree with them to use that branch.

For other activities like bug fixes, the branch to use is master. Now, if we get casual contributors that want to open a PR to fix something, if we keep master as default branch, their PR will be OK, even if they don’t know about our Git workflow.

5

We can only learn from experience. If y’all agree, we can try with this approach for the next release and check if it worked or not.

2 Likes