Hazelcast IMDG Documentation

This repository contains the Antora components for the Hazelcast IMDG documentation.

The documentation source files are marked up with AsciiDoc.

Docs Structure

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 with v/.

Release Workflow

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.

Patch Releases

This section guides you through the steps for releasing documentation for patch releases.

1. In the v/ branch for the minor version whose patch you are releasing, update the asciidoc.attributes.full-version field in the antora.yml file to the new patch version. For example, if you are releasing version 4.1.3, find the v/4.1 branch and update the asciidoc.attributes.full-version field in the antora.yml file with 4.1.3.

   Note	As soon as you push content to this branch, GitHub will trigger a new build of the site, which will include your new content.

2. If you are releasing a new latest version, submit a pull request to the develop branch of the hazelcast/hazelcast-docs repository to do the following:

   • Update the _redirects file with your release version of IMDG.

     Note	This 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 the variables.version field to your release version.

     Note	This 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"]
           },

Major and Minor Releases

This section guides you through the steps for releasing documentation for major and minor releases.

1. Create a new release branch from the master branch. For example if you’re working on content for version 5.0, create a branch named 5.0. You can add the new content and/or fixes to this branch before the release.

2. In the antora.yml file of your release branch, do the following:

   • Update the version, display_version, and asciidoc.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 becomes 5.0.

     version: '5.0'
     display_version: '5.0'
     asciidoc:
       attributes:
         full-version: '5.0'

3. If you are releasing a new latest-dev version, in the antora.yml file of the master branch, increment the version field to the latest-dev version. For example, 5.0-SNAPSHOT becomes 5.1-SNAPSHOT.

4. 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 the 5.0 branch.

   Note	As 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.

5. In the develop branch of the hazelcast/hazelcast-docs repository, submit a pull request to update the _redirects file with the new versions of IMDG.

   Note	This file is where we alias the latest-dev and latest 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 the hazelcast/hazelcast-docs repository, submit a pull request to update the search-config.json file with the new versions of IMDG.

     Note	This 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"]
           },

6. Delete the release branch. For example, if you released version 5.0, delete the 5.0 branch. This step helps to keep the repository clean of release branches.

GitHub Actions

To automate some elements of the build process, this repository includes the following GitHub Actions:

Table 1. GitHub Actions

File	Description	Triggers
validate-site.yml	Validates that all internal and external links are working	On a pull request to the master, archive, and v/ branches
build-site.yml	Builds the production documentation site by sending a build hook to Netlify (the hosting platform that we use)	On a push to the master branch and any v/ branches

Contributing

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.

License

All documentation is available under the terms of a Creative Commons License