Our release process

[matko]

I've written down a bunch of information about our release process under docs/release.md. Part of it is what we actually do, but a large part of it is more like how I would like to see things done.

Since this is an ongoing discussion, let's have a discussion thread here.

Some initial discussion already happened in pull request #588.

[matko]

The document in question can be found here: https://github.com/terminusdb/terminusdb/blob/main/docs/release.md

[spl]

@GavinMendelGleason says: “The release document doesn't describe the branch cascade.”

[spl]

Some things to discuss (as of release.md@81fe971):

We don't mention main when it comes to versioning. Currently, we are doing our development in main and then merging that into the release branch before tagging. I believe that is a fine plan for now, but we should probably also describe what we do when we are not doing that. That is, what are scenarios in which we would not merge from main into `v10.0? For example, suppose we want to make a minor fix to an older release.

How do we classify different kinds of changes? Are major and minor version releases always arbitrary? How do we deal with deprecations or breaking changes?

How do we deal with work that is expected to take longer than 1 week? Do we always do it on branches and PR it when it's production-ready? On a related note, is main always expected to be release-ready? Or are there times when main will be in the middle of some work-in-progress that we don't want to release? (That is, main could contain something that's either broken or just unfinished feature work.)

We should remove the “canary” description since we are no longer doing that.

I think the “urgent” can be removed here:

At any time, urgent issues may come up that will affect the upcoming release.

How much freedom do individuals have in changing the issues assigned to milestones? If I think I cannot complete a particular issue by the deadline, can I remove it from the milestone myself without consultation with others? If I think I can complete an additional issue by the deadline, can I can add it to the milestone without consultation?

Can we consider freezing main (i.e. no more PRs merged) at the end of the day before we release on the next day? I believe it's too rushed to try to wrap up development and release on the same day.

Can we consider doing the planning and release on a different schedule? For example, we could do them both on the same day instead of Monday and Thursday. I understand there's a tradition here. Since I wasn't around when this schedule was decided, I reserve the right to challenge the tradition and discuss alternatives. 😁

How do we coordinate releases across projects such as the Python and JavaScript clients? How do we coordinate version numbers?

[spl]

How do we coordinate releases across projects such as the Python and JavaScript clients? How do we coordinate version numbers?

Let's try to align the major and minor version numbers across the server and clients. It's informative for the user. But the clients can release patch versions at their own pace of development.

Sometimes, we may increment the minor number for only a client change or only a server change. We will try to coordinate these to keep the numbers the same.

[spl]

2 scenarios for using a release branch that does not involve main:

1. Emergency patch release that does not contain other commits from main
2. Fixing an older branch with a patch release.

[spl]

How do we classify different kinds of changes? Are major and minor version releases always arbitrary? How do we deal with deprecations or breaking changes?

We'll deal with it when we get there.

[spl]

How do we deal with work that is expected to take longer than 1 week?

@matko is in favor of feature flags, depending on the type of work. Example: idempotent insert. See src/config/terminus_config.pl for how we do configuration now. This could be hardcoded or using environment variables.

Alternative: feature branch.

Goal: Keep main in release-ready state as much as possible (barring our natural tendency towards erroring).

[spl]

Can we consider freezing main (i.e. no more PRs merged) at the end of the day before we release on the next day? I believe it's too rushed to try to wrap up development and release on the same day.

We all agree.