This section describes some important information about how this repository is structured:
-
The component name, version, and start page are configured in each branch’s
antora.yml
file. -
The navigation for all modules is stored in the ROOT module’s
nav.adoc
file. -
The docs site playbook instructs Antora to automatically build the site using content in the
master
branch as well as any branches that are prefixed withv/
.
Documentation for new releases is hosted in versioned branches that are prefixed with v/
.
We support documentation for the latest patch releases of minor versions. For example, content for the 4.1
version is hosted in the v/4.1
branch. This branch contains content for the latest patch release of version 4.1.
The latest-dev
content (snapshot content) is stored in the master
branch.
The documentation build process is triggered whenever you create a new branch with the v/
prefix, push to an existing v/
branch, or push to the master
branch.
This section guides you through the steps for releasing documentation for patch releases.
-
In the
v/
branch for the minor version whose patch you are releasing, update theasciidoc.attributes.full-version
field in theantora.yml
file to the new patch version. For example, if you are releasing version 4.1.3, find thev/4.1
branch and update theasciidoc.attributes.full-version
field in theantora.yml
file with 4.1.3.NoteAs soon as you push content to this branch, GitHub will trigger a new build of the site, which will include your new content. -
If you are releasing a new
latest
version, submit a pull request to thedevelop
branch of thehazelcast/hazelcast-docs
repository to do the following:-
Update the
_redirects
file with your release version of IMDG.NoteThis file is where we alias the latest
path in URLs.# Redirect latest imdg alias to the latest version /imdg/latest/* /imdg/4.1.2/:splat 200!
-
In the
search-config.json
file, change the value of thevariables.version
field to your release version.NoteThis file is where we specify which documentation version to index for the search. { "index_name": "prod_hazelcast_docs", "start_urls": [ { "url": "https://docs.hazelcast.com/imdg/(?P<version>.*?)/", "tags": [ "imdg" ], "variables": { "version": ["4.2"] },
-
This section guides you through the steps for releasing documentation for major and minor releases.
-
Create a new release branch from the
master
branch. For example if you’re working on content for version 5.0, create a branch named5.0
. You can add the new content and/or fixes to this branch before the release. -
In the
antora.yml
file of your release branch, do the following:-
Update the
version
,display_version
, andasciidoc.attributes.full-version
fields with the major and minor version of IMDG that you are releasing. -
Delete the
prerelease
field.For example version
5.0-SNAPSHOT
becomes5.0
.version: '5.0' display_version: '5.0' asciidoc: attributes: full-version: '5.0'
-
-
If you are releasing a new
latest-dev
version, in theantora.yml
file of themaster
branch, increment theversion
field to thelatest-dev
version. For example,5.0-SNAPSHOT
becomes5.1-SNAPSHOT
. -
When you’re ready to release, create the maintenance branch from the release branch. For example if you are releasing version 5.0, create a maintenance branch called
v/5.0
from the5.0
branch.NoteAs soon as you push the maintenance branch to the repository, GitHub will trigger a new build of the site, which will include your new content. -
In the
develop
branch of thehazelcast/hazelcast-docs
repository, submit a pull request to update the_redirects
file with the new versions of IMDG.NoteThis file is where we alias the latest-dev
andlatest
paths in URLs.# Redirect latest imdg alias to the latest version /imdg/latest/* /imdg/5.0/:splat 200! # Redirect latest-dev imdg alias to the latest-dev version /imdg/latest-dev/* /imdg/5.1-snapshot/:splat 200!
-
In the
develop
branch of thehazelcast/hazelcast-docs
repository, submit a pull request to update thesearch-config.json
file with the new versions of IMDG.NoteThis file is where we specify which documentation version to index for the search. { "index_name": "prod_hazelcast_docs", "start_urls": [ { "url": "https://docs.hazelcast.com/imdg/(?P<version>.*?)/", "tags": [ "imdg" ], "variables": { "version": ["4.2"] },
-
-
Delete the release branch. For example, if you released version
5.0
, delete the5.0
branch. This step helps to keep the repository clean of release branches.
To automate some elements of the build process, this repository includes the following GitHub Actions:
File | Description | Triggers |
---|---|---|
|
Validates that all internal and external links are working |
On a pull request to the |
|
Builds the production documentation site by sending a build hook to Netlify (the hosting platform that we use) |
On a push to the |
If you want to add a change or contribute new content, see our contributing guide.
To let us know about something that you’d like us to change, consider creating an issue.