Release procedure

[phw]

@rdswift This is about your questions on IRC. Great thing you enabled discussions here, I think for the docs it might be really useful as we otherwise lack a proper place for these discussions.

About https://github.com/rdswift/picard-docs/wiki/Publishing-a-New-Version is looking good to me. Only I am not sure about how the specific branches are handled.

Basically when doing a new minor number release (2.6, replacing previous 2.5.x) I would add a branch for 2.5 to retain the ability to update it individually if needed. But otherwise we push changes only to the master branch, right?

What if we want to prepare changes for an upcoming release, that we want to have shown in "latest", but not in the actual latest 2.x docs? E.g. we are still on 2.5, but we add some feature for Picard 2.6 we want to get documented. Would I then create a 2.5 branch (to allow updating the 2.5 path), then change the version to e.g. 2.6.0dev1, add the documentation changes and push this to master? This would then have latest include the changes, but 2.5 path not, right?

If this works, the process would work very well. I like it that we do most changes on a single branch (master), instead of having to maintain always multiple branches and merge between them.

[phw]

Just understood the logic of prerelease branches in https://github.com/rdswift/picard-docs/wiki/Repository-Structure now. So we would gather these changes for a upcoming release in a branch (as we had done in the past) and merge them to master once the release is done. This works for me well.

[rdswift]

Yes, exactly. The only thing to consider is how you name the temporary branch for collecting the changes. If it starts with a digit (0 to 9), any changes you push will trigger a full build of all outputs for all languages. This can be useful if you're wanting to confirm translation changes by looking at the output artifacts (if you don't already do that locally before pushing changes). Otherwise if you choose a branch name like next_release_2.6 it will only do the build in the base language (English) and won't build the translated documentation. In either case, the full build for all languages will occur when a pull request is entered to merge the branch into the master branch.

[rdswift]

@rdswift This is about your questions on IRC. Great thing you enabled discussions here, I think for the docs it might be really useful as we otherwise lack a proper place for these discussions.

Yeah, we really didn't have a good discussion forum for this stuff. This was the simplest option.

About https://github.com/rdswift/picard-docs/wiki/Publishing-a-New-Version is looking good to me. Only I am not sure about how the specific branches are handled.

Basically when doing a new minor number release (2.6, replacing previous 2.5.x) I would add a branch for 2.5 to retain the ability to update it individually if needed. But otherwise we push changes only to the master branch, right?

Ideally, yes, but it can always be created later if necessary as long as we can identify the point where the new release took over. That should be pretty easy.

Thinking about it some more, I may actually change that to simply add a tag to the master branch where a new major.minor version is released. That way we don't have extra major.minor branches that may not be used cluttering the repository. We should probably only create the old major.minor branch if and when a change is required to the old version of the documentation. Once created, it should remain in case further updates (corrections) are required.

What if we want to prepare changes for an upcoming release, that we want to have shown in "latest", but not in the actual latest 2.x docs? E.g. we are still on 2.5, but we add some feature for Picard 2.6 we want to get documented. Would I then create a 2.5 branch (to allow updating the 2.5 path), then change the version to e.g. 2.6.0dev1, add the documentation changes and push this to master? This would then have latest include the changes, but 2.5 path not, right?

Exactly right. The latest website path would show your v2.6.0dev1 documentation (and a v2.6 website path would be created), but the stable and v2.5 website paths would still show your latest v2.5.x documentation.

If this works, the process would work very well. I like it that we do most changes on a single branch (master), instead of having to maintain always multiple branches and merge between them.

Me too. The simpler we can make this, the less likely someone will misunderstand and do something unintended. I think that the automation is mostly bulletproof, but there's always something that has been missed that could come back to bite us.

[phw]

So let's go with this process and see how it works. For me this looks good for now, need to test it in practice :)