https://github.com/hazelcast/imdg-docs

Source content for the Hazelcast IMDG documentation
https://github.com/hazelcast/imdg-docs

Last synced: 6 months ago
JSON representation

Source content for the Hazelcast IMDG documentation

• Host: GitHub
• URL: https://github.com/hazelcast/imdg-docs
• Owner: hazelcast
• Created: 2021-01-04T11:00:13.000Z (about 5 years ago)
• Default Branch: v/4.2
• Last Pushed: 2024-09-18T10:03:58.000Z (over 1 year ago)
• Last Synced: 2025-07-07T01:39:37.467Z (6 months ago)
• Language: JavaScript
• Homepage: https://docs.hazelcast.com/imdg/latest
• Size: 50.1 MB
• Stars: 5
• Watchers: 29
• Forks: 30
• Open Issues: 39
• Metadata Files:
  • Readme: README.adoc

Awesome Lists containing this project

README

          
= 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]