Why is the release cycle so slow?

General
1

Typst is still in 0.x phase. According to semver rules anything may change at any time. Why is Typst then not released more often?

Most people test their issues on a code that is four months old and a lot of issues are long fixed. With this development speed I would expect at least weekly releases or when a new feature from the roadmap is complete.

2

As for 0.12, specifically: Things went a bit unplanned. We made promises about a specific feature (two-column floats), but then this feature and preceding refactorings took much longer than anticipated. We should’ve simply broken the promise and cut a release 2 months ago, but we didn’t and then missed that timeframe. Now it’s almost ready and 0.12 will be released soon. We have learned our lesson: Don’t make promises about a specific release and, even if, sometimes it’s better to break the promise than to hold back other features and bug fixes for a long time.

However, with that said, a release cycle of once a week is still unrealistic. A release involves more work than it might seem like: There’s a changelog to be written, the docs need to be reviewed in the rendered version (this often surfaces badly rendering examples), the web app needs to be updated, etc. My release checklist has ~30 steps and often it takes me almost a day. Of course, it would be less work with smaller release, but there’s also simply a constant amount of work and waiting involved.

I think weekly releases would also not make for a good end-user experience. The fact that we can make breaking changes in accordance with SemVer doesn’t make them less annoying for users. Dealing with breaking changes every week would be much more annoying than every 1-2 months, especially for package authors.

Another important point is stability: It’s not uncommon for regressions to sneak into the development version. Those then surface over time and also as part of the “call for testing” we do before releases. Typst 0.12 will also have such a call for testing. This means we can iron out more bugs before they reach most of the users.

Don’t get me wrong: We do agree that the current release cycle is too slow and we want to increase the release frequency after 0.12. But we would still be talking every 6-8 weeks or something like that, not every week. (This is not a promise! :p)

23 Likes
3

IMO, you can cross out 1 step from your checklist (or make it almost non-existent) if Typst would use Keep a Changelog or just 1 of its concepts:

How can I reduce the effort required to maintain a changelog?

Keep an Unreleased section at the top to track upcoming changes.

This serves two purposes:

  • People can see what changes they might expect in upcoming releases
  • At release time, you can move the Unreleased section changes into a new release version section.
4

I think that would be more total work. It would mean either updating it frequently or constantly making comments on PRs that don’t update it. And at the end the changelog would probably be less coherent and consistent or I would still have to edit it.

1 Like
5

I think it depends on the person and the exact execution. Overall, the work won’t magically decrease, it is just spread over a long period of time (but the intensity/load per day will be totally manageable). This also allow keeping a fresh state of what has been changed in your head at any point in time — no need to remember something or go through a long list of merged PRs.

The way I see it, it would be easier to do if you just update the changelog separately (i.e., alone) after a particular PR is merged, kinda like you do now. Directly to the main or through a standalone PR. This will remove all the coordination overhead compared to demanding/asking for a changelog to be edited by each contributor or something like that.

But you do you, I just pitched a small idea I had.

6

Wouldn’t that duplicate the commit count and add overhead with merging and stuff? Personally, I don’t mind writing the changelog. Doing it all in one go is okay and quite productive. No context switching. But it still takes time, just wanted to mention that.

Sure, I’m happy to discuss it!

7

First one is obviously true, but overhead with merging? Which overhead? The fact that you have to create a PR just to edit the changelog file? If you use gh then it won’t take more than… 10 s? gh pr create (with default or no comment) and gh pr merge. There won’t be any merge conflicts, if that is what you’re saying.

Nice.

No doubt, doing it in one go is the most efficient way in terms of total time spent. The key difference is the time spent per day/session. With current approach you spend more time (30 m min?), but it is done in 1 day. With Keep A Changelog approach, you would spend (theoretically) around 1–2 m per PR (git checkout -b <branch>, "$EDITOR" <file>, git add -u, git commit -m 'updated changelog', gh pr create, gh pr merge).

In itself, there is no context switching (but overall it does add something new to the daily workflow). Moreover, you already know what you want to add to the changelog (the PR you want to mention there just has been merged).

I’d say, if you don’t spend too much time on this now, then it is probably not worth changing the workflow. But in any case, I recommend trying this in practice just to see if it’s for you or not. This may at first be uncomfortable (maybe), but as with all things: the more you do the same thing, the faster it becomes a routine that you get used to and do it more “automatically” (e.g., the classic “brushing your teeth” etc.) If this doesn’t work out for you after several small changelog updates (let’s say more than 10), then you can stop at any moment and do “one big update” as usual.

So what I’m trying to say is that there are no risks in trying the new approach. You might change your mind after trying. After all, it’s not “just some random rule that no one knows about”, it’s pretty well known in dev/FOSS world and probably is a de facto standard (but I don’t know for sure).

1 Like
8

My 2 cents after doing the [Unreleased] section on several projects:

Upsides

  • It does indeed somewhat reduce the time of making a release. I was previously crawling months of git logs to find the relevant parts.
  • It gives an updated overview of what has been done which can be used to judge whether it is time to make a new release.

Downsides

  • Without CI checks, it’s easy to forget and then one needs another PR just to update it, which I find messy and annoying.
  • It’s a pretty consistent point of conflict, when you try to do it as part of the PR.

Personal conclusion: Takes more time overall, but still worth it mostly for the quick overview of what’s been done since the last release.

Just sharing my experience. I do not mean to suggest anybody to change their ways.

1 Like
9

Thanks for your input! Sounds pretty close to how I imagine it. I think for the time being I’m happy with the way we do it now.

3 Likes