Version and Release Policies

Version policy

Starting with the 2.0.0, Asciidoctor core uses semantic versioning as its versioning system. This versioning system is used as a way to communicate with users and set expectations about what types of changes a release will contain. Each software release is versioned as major.minor.patch (e.g., 2.0.0).

Major

Major releases occur when there are substantial changes in functionality or when new functionality breaks backwards compatibility. Releases within the same major release line will maintain API compatibility.

Minor

Minor releases add new features, improvements to existing features, and fixes that maintain backwards compatibility.

Patch

Patch releases fix bugs and maintain backwards compatibility. Only the latest minor release of a major release line will receive patches. Patch releases happen as needed depending on the urgency of the fix.

Prerelease

Major and minor releases may include prerelease versions (major.minor.patch-alpha.n | -beta.n | -rc.n). Once a release candidate (rc) has been thoroughly tested, the stable release will be published.

Version line branches

Every minor release of Asciidoctor has its own release branch, known as a version line branch (e.g., v2.0.x, v2.1.x, etc). These version line branches are named using the pattern v<major>.<minor>.x (e.g., v2.0.x, v2.1.x, v3.0.0, etc). (The v prefix is used to distinguish version line branches and to make matching them using a pattern simpler). Patch releases for a minor release are made from these version line branches. Typically, though, patch releases are only made for the current (aka latest) minor release. Exceptions are made on a case-by-case basis to address security vulnerabilities and other high-priority issues.

Often, the current minor release is stored on the default branch of the repository. This simplifies the management of the source code as it avoids having to merge the same change into multiple branches. Once room needs to be made for the next minor (which could be the .0 minor release of the next major), the minor release is swept off to its own version line branch.

Generally, the process for managing version line branches is as follows:

  • Publish the .0 patch release (e.g., 2.1.0 or 3.0.0)

  • Make bug fixes to the default branch and publish patch releases as necessary

  • Create a minor branch and update the version in the default branch to be the next minor (or the next major, if the situation calls for it)

  • Commit changes for the next minor (or major) to the default branch

  • Repeat

The documentation is organized by minor version and is thus pulled from the minor version branches.

Release Policy

General Availability (GA)

A release line, such as Asciidoctor 2.x, enters general availability on the date the initial, final major version (e.g., Asciidoctor 2.0.0) of the software is released and available for download.

Active

Release line is being actively improved and supported.

Maintenance

Once a release line enters its maintenance period, only its most recent minor version will receive critical security patch releases. A release line starts this phase 30 days after the next major release line goes GA.

End of Life (EOL)

The date after which the release line no longer receives support or releases. Once a release line reaches EOL, the CI workflow for the corresponding branch is disabled to indicate it’s no longer receiving updates.

Dates are formatted as year/month/day.

Project Release Line Latest Release Status GA Maintenance EOL

Asciidoctor Core 2.x

2.0.16

Active

2019/03/22

TBD

TBD

Asciidoctor Core 1.5.8

1.5.8

EOL

2018/05/02

2019/04/22

2019/12/31

The information on this page is believed to be accurate as of the date of publication, but updates and revisions may be posted periodically and without notice.