docs: Add release process details and workflow

[placer14]

Documentation of the release process I follow for visor so others may participate.

[frrist]

Perhaps the release process deserves its own file?

I generally expect README's to contain tips on getting started, a couple usage examples, and pointers for contributing -- short and sweet. Since publishing a release is the responsibility of maintainers I'd be okay with it moving to its own document.

[frrist]

Should git-chglog be used for this step (and the hotfix)? Could mention the make command for it as well.

[placer14]

I don't know if the make command is useful as this workflow requires providing arguments (to define the next tag being created within --next-tag arg) which make requires envvars for. I'm considering removing the target from the makefile and letting the doc stand alone.

[frrist]

In favor of dropping the makefile target.

[iand]

Meta question: why isn't cutting a release as simple as tagging master once the changelog has been updated?

I think the current method is process heavy and more complex than we need at this stage of development. I'd like to see us tagging minor releases every few day and deploying them, which means keeping a lightweight approach for as long as possible.

I'd also like to avoid having long lived version branches with hotfixes. Unless it's unavoidable we should prefer to fix in master and increment the patch version.

The main friction is the schema version. We should be very clear in the changelog when a schema version changes and whether it is destructive or breaking.

[iand]

tidy should be done before build so the build uses the exact same versions as specified in go.mod/go.sum. Ideally go build should be run with -mod=readonly so it doesn't change the files. This is the new default in the upcoming version of Go.

[iand]

As a follow-on thought: a new schema version should always result in at least a minor version increment.

[placer14]

why isn't cutting a release as simple as tagging master once the changelog has been updated?

I've made the following assumptions:

1. That release candidates are a worthwhile step in validating our release. (Primarily because the feature set in the RC is pinned within the branch and does not move unless done so explicitly.)
2. Deltas between release candidates should ONLY include fixes and not features or interface changes. (To ensure that prior validation performed on the RC has minimal opportunity to regress from other major changes applied.)

If we simply tag latest master, there is no guarantee of the 2nd assumption being true.

[iand]

why isn't cutting a release as simple as tagging master once the changelog has been updated?

I've made the following assumptions:

1. that release candidates are a worthwhile step in validating our release.

2. I also believe that deltas between release candidates should ONLY include fixes and not features or interface changes.

If we simply tag latest master, there is no guarantee of the 2nd assumption being true.

I think release candidate management is a complexity that we don't need yet. We don't have a pattern of regular releases to base our decisions on nor do we have a good enough testing regime to be confident of catching regressions or problems in a release candidate. This is made even more difficult if a candidate involves a breaking schema change.

At the moment I don't feel we have any release momentum and each release seems to involve a huge amount of work.

At this stage of our development I think we should be more flexible and responsive. Tag minor releases regularly and attempt deployment as soon as we tag. Prefer to roll forward, fixing issues in a new minor release. Roll back only if there is no choice.

[placer14]

I fully support a leaner release cycle, but also note that we are adding many dependencies onto the schema outputs of visor. I am looking for room in the release process to validate these dependencies (automatically or otherwise). That said, I can be satisfied with defaulting to the fast path until it becomes too painful.

[placer14]

Update with feedback applied. Looking for one last review since we're discussing process here.

[frrist]

The migration link 404's for me, but maybe it's a PR/formatting thing?

[placer14]

Good catch!

[frrist]

LGTM!