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 tags that are prefixed with v.

Release Workflow

Documentation for new releases is hosted in versioned tags that are prefixed with v. For example, content for the 4.1.1 version is hosted in the v4.1.1 tag. The latest-dev content is stored in the master branch

The documentation build process is triggered whenever you push a new tag to this repository or commit to the master branch.

Patch Releases

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

1. Find the .z branch for your version. For example, if you’re working on content for version 4.1.2, find the branch named 4.1.z.

   Tip	For guidance on writing content, see the contribution guidelines.

   Note	If a branch for your major or minor version does not exist, see Major and Minor Releases.

2. When you are ready to release, create a new release branch from the .z branch and name it with the full version number that you are releasing. For example, if you are releasing version 4.1.2, name the branch 4.1.2.

3. In the antora.yml file of your release branch, update the version field with the version of IMDG that you are working on. For example from 4.1.2-SNAPSHOT to 4.1.2.

   version: 4.1.2

4. Tag the latest commit in your release branch with a v followed by the version number.

5. If you have made any changes since creating your release branch, merge those changes back into the .z branch.

6. Delete your release branch.

   ⚠️	Do not delete the .z branch. This branch is for writing content for future patch releases.

7. In the antora.yml file of the .z branch, increment the version field. For example, 4.1.2-SNAPSHOT becomes 4.1.3-SNAPSHOT.

8. If you are releasing a new latest version, in the develop branch of the hazelcast/hazelcast-docs repository, submit a pull request to 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!

The documentation site will now be built, including content from your tagged version.

Major and Minor Releases

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

1. If you’re writing content for a new major or minor release, make your changes in the master branch.

2. If you’re writing content for a new minor version of a previous major release, create a {version}.y branch and make your changes in that branch. For example if version 5.0 was already released and you plan to add content for version 4.3 then you need to create a branch named`4.y`.

   Tip	For guidance on writing content, see the contribution guidelines.

3. When you are ready to release, create a new release branch from the master or .y branch and name it with the full version number that you are releasing. For example, if you are releasing version 5.0, name the branch 5.0.

4. 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.0-SNAPSHOT.

5. To make it easier to amend your release for future patch versions or to fix typos, create a {version}.z branch from your release branch. For example if your release branch is named 5.0, create a branch named 5.0.z.

6. In the antora.yml file of the .z branch, increment the version field. For example, 5.0 becomes 5.0.1-SNAPSHOT.

7. In the antora.yml file of your release branch, update the version field with the version of IMDG that you are working on, and delete the prerelease field. For example version 5.0-SNAPSHOT becomes 5.0.

   version: 5.0

8. Tag the latest commit in your release branch with a v followed by the version number.

9. If you have made any changes since creating your release branch, merge those changes back into the .z branch (and if applicable also to master branch).

10. Delete your release branch.

    ⚠️	Do not delete the .z branch. This branch is for writing content for future patch releases.

11. 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!

The documentation site will now be built, including content from your tagged version.

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 *.z branches
build-staging.yml	Builds the staging documentation site by sending a build hook to Netlify (the hosting platform that we use)	On a pull request to the master, archive, and *.z 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 tags whose names start with v

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.