search

asciidoctor / docs.asciidoctor.org

The Antora playbook project (i.e., site manifest) for the Asciidoctor documentation site.
https://docs.asciidoctor.org
MIT License
14 stars 18 forks source link

Set fixed Asciidoctorj to avoid publishing unreleased changes #64

Closed abelsromero closed 3 years ago

abelsromero commented 3 years ago

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?

mojavelinux commented 3 years ago

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.

mojavelinux commented 3 years ago

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.

abelsromero commented 3 years ago

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. If changes need to me moved selectively this seems a lot of work to place on the repo mantainer.

mojavelinux commented 3 years ago

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.