Set fixed Asciidoctorj to avoid publishing unreleased changes #64
Conversation
|
Once multiple versions of the docs exist, they will start showing up on the site. So this is a natural progression. However, I strongly advise against using tags. Rather, the docs should be pulled from the version-line branches like v2.2.x, v2.3.x, etc.* The default version should match the greatest version-line that is currently being published. Any unreleased version-lines (such as main) should be marked as a prerelease. (That's how Antora ends up selecting the default version to show). It's true that there is still risk that docs that apply to a patch release become available before that patch release is made. But in sticking with semantic versioning, a patch release should not really have user-facing docs. So I think that actually encourages the right practice on the software side. * You can see this example in Antora's own docs at https://docs.antora.org. |
|
I should mention that once the branch for Asciidoctor core 2.0.x is made, the playbook will be rerouted to that branch so that the docs are not affected by the activity in the main branch. We may still decide to publish the docs from the main branch, but it will be marked as a prerelease until the 2.1.0 release is cut. |
|
I see the advantatges here, and even when you say there is still risk that docs that apply to a patch release become available I also see the bright side in that one can relase improvements in the docs that do not break anything. But I don't understand how main and the release branch are related. Looked into antora and asciidoctorj and assumed changes from main were migrated as-is to the release branch, but comparing the history that doesn't seem to be the case. Not at least in a 1:1 way. |
|
The approach we take in Antora, Asciidoctor, and Asciidoctor PDF, among others, is to treat the default branch of the repository as the current minor. When a new minor (which could be the .0 of the next major) comes into the picture, then the code for the previous minor gets moved to a v* branch. So really, the default branch is, itself, a release line branch. I explain this process on the following page: https://docs.asciidoctor.org/about/version-and-release-policies/#version-line-branches It's true that there is sometimes a period when the docs changes need to be applied to more than one branch. Fortunately, GitLab makes this easy because it allows you to cherry pick changes from one branch to another (see https://docs.gitlab.com/ee/user/project/merge_requests/cherry_pick_changes.html). GitHub, on the other hand, doesn't have this feature. But many GitHub users have created a bot to help with this. We can adopt something similar in the Asciidoctor organization. |
antora-playbook.yml
Outdated
| @@ -25,7 +25,7 @@ content: | |||
| branches: v2.2.x | |||
| start_path: docs | |||
| - url: https://github.com/asciidoctor/asciidoctor-cli.js | |||
| branches: master | |||
| tags: v2.4.3 | |||
There was a problem hiding this comment.
This change is being proposed does not match the subject of the PR. This is the asciidoctor-cli.js content source.
I strongly encourage the AsciidoctorJ project to follow the release line branch strategy outlined on this page: https://docs.asciidoctor.org/about/version-and-release-policies/#version-line-branches
abelsromero
force-pushed
the
prevent-unreleased-changes-in-Asciidoctorj
branch
from
c8435b6 to
6fc9de8
Compare
antora-playbook.yml
Outdated
| @@ -28,7 +28,7 @@ content: | |||
| branches: master | |||
| start_path: docs | |||
| - url: https://github.com/asciidoctor/asciidoctorj | |||
| branches: main | |||
| tags: v2.4.3 | |||
There was a problem hiding this comment.
Can you work with the AsciidoctorJ project to create a release branch for v2.4.x?
There was a problem hiding this comment.
Just fixed to avoid confusions, was not meant to merge. I guess, we can invite @robertpanzer here to discuss the process, I am still figuring out the workflow.
There was a problem hiding this comment.
Sure, I can create a branch v2.4.x tomorrow pointing to the last released tag v2.4.3.
There was a problem hiding this comment.
If I understand the document correctly we can treat main as v2.5.x until it's clear that we will have a change that requires going to 2.6 or even 3.0, at which point we would branch of v2.5.x from the last released tag, right?
There was a problem hiding this comment.
In the future we probably need to think better about when we pull the trigger for a next minor version though.
Anything that is worth documenting and that is not part of vx.y.0 should probably pull the trigger for a next minor version, or we explicitly document that as "requires vx.y.3".
There was a problem hiding this comment.
If I understand it correctly all @robertpanzer is saying is correct. Furthermore since 2.5.0 was released as RC only, it makes sense to keep it in main for now.
There was a problem hiding this comment.
With the v2.4.x branch pointing to the we won't have issues with documentation. For context, what rised my concerns was this comment where a user was trying to user latest unreleased changes asciidoctor/asciidoctorj#1025 (comment).
Anything that is worth documenting and that is not part of vx.y.0 should probably pull the trigger for a next minor version, or we explicitly document that as "requires vx.y.3".
As you say, to me, it should be next minor. Following the same code rules, unless the change is something required for urgency or security fix, it should wait.
There was a problem hiding this comment.
If I understand the document correctly we can treat main as v2.5.x until it's clear that we will have a change that requires going to 2.6 or even 3.0, at which point we would branch of v2.5.x from the last released tag, right?
Correct. The idea is to create the branch as late as possible to avoid having to maintain parallel branches that are essentially the same.
There was a problem hiding this comment.
I just pushed a branch v2.4.x: https://github.com/asciidoctor/asciidoctorj/tree/v2.4.x
There was a problem hiding this comment.
Updated PR to point to it. Thanks you both for the effort 🙇♂️
abelsromero
force-pushed
the
prevent-unreleased-changes-in-Asciidoctorj
branch
from
6fc9de8 to
26173d0
Compare
Recently we updated the docs according to some code changes and those changes went life in the docs.
However, those changes are new methods so that makes the docs invalid and already one user was confused.
This PR updates the configuration to point to the latest stable to avoid this problem. On new releases we will have to update the tag to the latest stable branch, or create a fixed "latest" branch in the repo.
Now, I am not sure about this change. Seems to me we should not be the first to encounter this issue, however, I see all configuration in the playbook uses main branches. I am understanding something wrong?