= Hazelcast IMDG Documentation // Settings: ifdef::env-github[] :warning-caption: :warning: endif::[] // URLs: :url-org: https://github.com/hazelcast :url-contribute: https://github.com/hazelcast/hazelcast-docs/blob/develop/.github/CONTRIBUTING.adoc :url-ui: {url-org}/hazelcast-docs-ui :url-playbook: {url-org}/hazelcast-docs :url-staging: https://brave-engelbart-6d53bf.netlify.app/ :url-cc: https://creativecommons.org/licenses/by-nc-sa/3.0/

image:https://img.shields.io/badge/Build-Staging-yellow[link="{url-staging}"]

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 {url-playbook}[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.

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

. If you are releasing a new latest version, submit a pull request to the develop branch of the link:{url-playbook}[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.

• [source,bash]

  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.

• [source,json]

  { "index_name": "prod_hazelcast_docs", "start_urls": [ { "url": "https://docs.hazelcast.com/imdg/(?P.*?)/", "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.

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

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

• [source,yaml]

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

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

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

. 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. + [source,bash]

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.

• [source,json]

  { "index_name": "prod_hazelcast_docs", "start_urls": [ { "url": "https://docs.hazelcast.com/imdg/(?P.*?)/", "tags": [ "imdg" ], "variables": { "version": ["4.2"] },

. 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:

.GitHub Actions [cols="m,a,a"] |=== |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 {url-contribute}[contributing guide].

To let us know about something that you'd like us to change, consider {url-org}/imdg-docs/issues/new[creating an issue].

== License

All documentation is available under the terms of a link:{url-cc}[Creative Commons License]