Hazelcast Platform Documentation

This repository contains the Antora components for the Hazelcast Platform 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 main 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/. The latest-dev content (snapshot content) is stored in the main branch.

We support documentation for the latest patch releases of minor versions. For example, content for the 5.0 version is hosted in the v/5.0 branch. This branch contains content for the latest patch release of version 5.0.

Note	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 `main` branch.

Snapshot Releases

Add the new snapshot version to the following:

Repository	Branch	File	Fields
`hz-docs`	`main`	`docs/antora.yml`	`version` `display_version` `full-version` `asciidoc.attributes.page-latest-supported-java-client`
`hazelcast-docs`	`main` and `develop`	`_redirects`	`/hazelcast/latest-dev/*`
		`search-config.json`	`start_urls.tags` `start_urls.variables.version`
`management-center-docs`	`main`	`docs/antora.yml`	`asciidoc.attributes.page-latest-supported-hazelcast`

Latest Releases

Add the major.minor version to the following:

Repository	Branch	File	Fields
`hz-docs`	`v/{major.minor version}`	`docs/antora.yml`	`version` `display_version`
`hazelcast-docs`	`main` and `develop`	`_redirects`	`/hazelcast/latest/*`
		`search-config.json`	Create a new object in the `start_urls` array. `{ "url": "https://docs.hazelcast.com/hazelcast/(?P<version>.*?)/", "tags": [ "hazelcast-{major.minor version}" ], "variables": { "version": ["{major.minor version}"] }, "selectors_key": "hz" }`
`management-center-docs`	The `v/{version}` branch where `version` is the value of the `asciidoc.attributes.page-latest-supported-mc` field in the `docs/antora.yml` file of the `hz-docs` repository	`docs/antora.yml`	`asciidoc.attributes.page-latest-supported-hazelcast`

Add the full version major.minor.patch to the following:

Repository	File	Fields
`hz-docs`	`docs/antora.yml`	`full-version` `asciidoc.attributes.page-latest-supported-java-client`

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 5.0.3, find the v/5.0 branch and update the asciidoc.attributes.full-version field in the antora.yml file with 5.0.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.

Creating Release Branches

If you are releasing a new major version, create a release branch from the main branch.

For example, if you are releasing version 5.1, create a new release branch named 5.1 from the main branch.
Update the fields mentioned in Latest Releases.
Remove the prerelease: true field from the docs/antora.yml file of the hz-docs repository.

Important
If you are creating a branch for a beta release, do not remove this field.
When you are ready to release, create a maintenance branch from the release 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.
Make sure to delete the release branch.

For example, if you released version 5.1, delete the 5.1 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 `main`, `archive`, and `v/` maintenance 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 `main` branch and any `v/` maintenance branches
`backport.yml`	Backports commits to maintenance branches	On a push to the `main` branch that originated from a pull request with the `backport` label

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.

npm scripts

For deployment and development this repository includes the following npm scripts:

Table 2. npm scripts

Script	Description	Notes
`npm run build`	Builds a production version of the docs from this repo	This script depends on Netlify env vars (`REPOSITORY_URL` and `BRANCH`) which you can encode using e.g.: `export REPOSITORY_URL=https://github.com/hazelcast/hz-docs && export BRANCH=pull/445/head && npm run build` You should generally just use build-local though.
`npm run build-local`	Builds a local version of the docs from this repo	By default, it will build all content sources taken from the global antora-playbook. But if you want to build less, please modify the local antora-playbook.
`npm run validate-docs`	Validates docs	It will take into consideration all content sources taken from the global antora-playbook.
`npm run check-orphan-pages`	Checks orphan pages

Note	Before running any of the scripts please make sure you have installed all latest npm packages via `npm i`.

License

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

hazelcast/hz-docs

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors 86

Uh oh!

Packages