Skip to content

Latest commit

 

History

History
54 lines (34 loc) · 3.56 KB

MAINTAINING.adoc

File metadata and controls

54 lines (34 loc) · 3.56 KB
Raw

How to Version Documentation

1. Create Versioned Branch:

  • Begin by creating a dedicated branch for a new release, following semantic versioning, for example, 2.452.x since software release aren’t mapped to patch releases but to LTS stable releases.

Note
 The main branch will contain documentation for the next release and when a release candidate will be released and another branch is created from the main branch. In simple terms, The main branch will always contain documentation for the next release and some time before the release, we will create a versioned branch.

2. Update antora.yml in Versioned Branches:

  • Ensure that all antora.yml files within this branch contain a consistent value for the version key. This value will be displayed to the users accessing the documentation.

3. Add Branch to antora-playbook.yml:

  • Add the newly created branch, such as 2.452.x, into the antora-playbook.yml file located in the playbook directory. This inclusion instructs Antora to fetch this branch and generate documentation for it, aligned with the version specified in the antora.yml file.

content:
  sources:
    - url: https://github.com/PATH/jenkins-docs.git
      branches: [main,2.452.x]
      start_paths: [docs/tutorials, docs/user-docs, docs/solutions]
      # developer docs are un-versioned that's why they are to be fetched individually
    - url: https://github.com/Vandit1604/jenkins-docs.git
      branches: [main,2.452.x]
      start_paths: [docs/dev-docs, docs/events, docs/security, docs/sigs, docs/projects, docs/images, docs/books, docs/community, docs/project, docs/about, docs/download]

  • The content.sources.branches key should be updated with the name of the newly created 2.452.x branch

Note
 The antora.yml file at the root of each component contains a version: key, denoting the version displayed on the site, not the branch’s name.

For non-versioned components, antora.yml contains version: ~, while display_version: 'latest' is set to showcase the latest content.

How each branch is different?

The name of each branch will be same and the component descriptors i.e antora.yml in each branch will contain the corresponding version as the value for the version key.

Why Use Branches for Versioning?

Branches offer the right balance. By creating a new branch from an existing reference in the repository to hold a new version, the repository only stores what’s changed since that branch point. And that branch can receive updates at any time. That’s what git does best.

Antora offers several methods for versioning content, including branches, folders, and tags. Branches are recommended due to their flexibility:

  • Continuous Documentation Updates: Branches enable ongoing updates to documentation even after software releases, allowing for seamless management and maintenance.

  • Efficient Version Control: Compared to storing versions in folders, using branches avoids the need to manually copy files for each new version, leveraging Git’s functionalities for version comparison, management, and merging.

  • Documentation Flexibility: Unlike tagging, which freezes documentation once created, branches facilitate ongoing modifications and updates to the documentation.