= 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:
antora.yml
file.nav.adoc
file.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:
+
_redirects
file with your release version of IMDG.NOTE: This file is where we alias the latest
path in URLs.
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.
== 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:
+
version
, display_version
, and asciidoc.attributes.full-version
fields with the major and minor version of IMDG that you are releasing.prerelease
field.For example version 5.0-SNAPSHOT
becomes 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.
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]/imdg/latest/* /imdg/5.0/:splat 200!
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.
. 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]