Operations manual

Prereqs

• Node.js

• npm

Installation

To install the required packages:

npm i

Generating HTML output

To convert asciidoc source to HTML:

npm run build

Viewing HTML output

To view the built site, launch a local server:

1. npm start

2. In a browser tab, go to localhost:8000

Live preview

When you run npm start, the project is monitored for updates to asciidoc files.

If a change to an asciidoc file is detected the site is automatically rebuilt.

Enable automatic cherry-picking on a PR

To enable automatic cherry-picking on a PR, add the label auto-cherry-pick to it. Without it, the responsible GitHub action is not going to be triggered.

To select the target branches you would like to cherry-pick your PR to, add labels of the following structure: auto-cherry-pick-to-<targetBranch>. For example: auto-cherry-pick-to-main to cherry-pick it to the branch main or auto-cherry-pick-to-5.x for the branch 5.x. You may even add new labels for branches that do not have such a label yet.

The feature is triggered by either merging a PR with the auto-cherry-pick label or by adding the auto-cherry-pick label to an already closed and merged PR. In the latter case, ensure that you first add the labels containing the target branches and then finally the auto-cherry-pick label. Otherwise the automation starts without any target branches.

Details

The PRs created by this GitHub action will have their heading prefixed with [Cherry-pick][<targetBranch>]. So, for example, for main as the target branch and some changes as the original PR heading, it results in [Cherry-pick][main] some changes as the heading for the cherry-picked PR. In case an assignee was set for the original PR, the cherry-picked PRs will also receive the same assignee. You must add reviewers manually after the cherry-picked PRs have been created.

The creation of cherry-picked PRs can take a few minutes. If you are an assignee of the original PR, you receive an email notification once the cherry-picked PRs have been created. The original PR is updated with a comment that contains links to the newly created cherry-picked PRs.

In case of a merge conflict while cherry-picking to a specific release branch, the branch will be skipped. Information on skipped branches is also included in the comment added to the original PR. In that case you have to take care of cherry-picking manually and resolve the conflicts. This is not going to influence the other release branches as long as they do not have conflicts.