CIRCLECI.md

CircleCI Workflows

Plain build

The plain-build workflow is automatically triggered whenever there is a push in a PR.

It is configured to build the docs without re-generating the examples (using a committed cache file).

A plain build is sufficient for the following types of changes:

• Creating a new page or editing an existing page, as long as no code blocks with front matter (i.e. generated examples) are added or modified.

• Adding a new or editing an existing HTTP API endpoint description, as long as no accompanying ```curl examples are added or modified. The plain-build workflow includes validation at each run using swagger-cli.

The build report including OpenAPI syntax validation can be found in the generate-summary check in GitHub.

Invoke Args:

Parameter Type	Name	Value
string	workflow	plain-build
string	deploy-url	deploy-preview-{PR_NUMBER}

Deploy a plain build to production

To update the live documentation independently of an ArangoDB release, for example, because of changes to the Contextual Data Platform docs or to publish documentation improvements before the next ArangoDB release, follow the steps below.

1. Go to CircleCI and select the docs-hugo project.
2. Select the main branch.
3. Click the Trigger Pipeline button.
4. Add the parameters described below.
5. Click Trigger Pipeline.

Parameters used for docs-only publication

Parameter type	Name	Value
string	workflow	release

(The release-type is docs by default)

The docs-only release workflow runs a plain build of the documentation and deploys to production at https://docs.arango.ai without approval step.

Example generation

The generate workflow can be automatically triggered from a PR.

Necessary when adding or editing the following content:

• AQL examples (```aql with front matter)
• arangosh (JavaScript API) examples (```js with front matter)
• cURL HTTP API examples (```curl)

Commands you can use in GitHub comments on PRs:

• /generate: to build examples for the preview
• /commit: to commit the previously generated examples to the PR
• /generate-commit: to build and commit the examples in one go

These commands work only if you indicate the upstream PRs or a nightly image in the PR description, as they are required for the compile step.

/generate

When commenting a PR with the /generate command, the following arguments are invoked:

Parameter type	Name	Value
string	workflow	generate
string	arangodb-3_10	Upstream reference for 3.10
string	arangodb-3_11	Upstream reference for 3.11
string	arangodb-3_12	Upstream reference for 3.12
string	generators	examples
string	deploy-url	deploy-preview-{PR_NUMBER}

/commit

• workflow: commit-generated

/generate-commit

When commenting a PR with the /generate-commit command, the following arguments are invoked:

Parameter type	Name	Value
string	workflow	generate
string	arangodb-3_10	Upstream reference for 3.10
string	arangodb-3_11	Upstream reference for 3.11
string	arangodb-3_12	Upstream reference for 3.12
string	generators	examples
string	deploy-url	deploy-preview-{PR_NUMBER}
boolean	commit-generated	true

cache override

You can override the cache of an example with the override CircleCI parameter in the generate workflow.

The override parameter is a comma-separated string of regexes.

The comma will be replaced by | and creates an OR of all the regexes in the override parameter.

The example below overrides all examples having http or starting with aql in the example name. You can also specify the name of the example to override the cache for, i.e. AqlDateTimeToLocal_3.

Note that the override is valid for all versions that are specified using the arangodb parameters. You can override the example output for a single version or for multiple versions.

Parameter type	Name	Value
string	workflow	generate
string	arangodb-3_10	Upstream reference for 3.10
string	arangodb-3_11	Upstream reference for 3.11
string	arangodb-3_12	Upstream reference for 3.12
string	generators	examples
boolean	commit-generated	true
string	deploy-url	deploy-preview-{PR_NUMBER}
string	override	http,^aql.*

Upstream references

Documentation pull requests specify upstream references like so:

- 3.10: 
- 3.11: https://github.com/arangodb/arangodb/pull/12345
- 3.12: arangodb/enterprise-preview:devel-nightly

The above example indicates that ArangoDB versions 3.11 and 3.12 contain changes relevant to the docs PR, but 3.10 does not. Relevant changes are typically behavior changes of arangod that will be visible in documentation examples.

For 3.11, a link to a PR in the arangodb/arangodb repository is given. It is used by the GitHub integration to determine the feature branch to compile and use for generating examples. Do not specify a link when manually triggering a pipeline in CircleCI but the branch name (like feature/new-aql-function)!

For 3.12, an ArangoDB Enterprise Edition image hosted on Docker Hub is specified. Using Docker images has the advantage that the compilation of ArangoDB can be skipped, making the example generation faster. Of course, this requires that an image containing relevant changes to ArangoDB exists.

Release workflow for ArangoDB releases

To run a release job for a new ArangoDB patch release (e.g. 3.11.4), minor release (e.g. 3.12.0), or major release (e.g. 4.0.0), follow the steps below.

1. Go to CircleCI and select the docs-hugo project.
2. Select the main branch.
3. Click the Trigger Pipeline button.
4. Add the parameters described below.
5. Click Trigger Pipeline.

Parameters used for ArangoDB release workflow

Parameter type	Name	Value
string	workflow	release
string	release-type	arangodb
string	docs-version	3.11 (the docs version folder)
string	arangodb-branch	3.11.4 (the arangodb/arangodb branch to compile)
string	arangodb-version	3.11.4 (updates the versions.yaml file)

The ArangoDB release workflow includes the following jobs:

• generate workflow (all examples are re-generated for the specified version)
• a release branch and pull request is created with the generated content, which needs to be reviewed and merged on GitHub
• once merged, the workflow in CircleCI needs to be approved to start deploying to production at https://docs.arango.ai

If any of the examples or generated content fails, the workflow fails as well. The build report can be found in the generate-summary check on GitHub.

Scheduled workflow

The generate-scheduled workflow is automatically triggered every Thursday. It is configured in the CircleCI web interface at Project Settings > Triggers.

This workflow uses predefined arguments and generates the data files of the following:

• metrics
• startup options
• error codes
• optimizer rules

Invoke Args:

Parameter type	Name	Value
string	workflow	generate-scheduled
string	arangodb-3_10	arangodb/enterprise-preview:3.10-nightly
string	arangodb-3_11	arangodb/enterprise-preview:3.11-nightly
string	arangodb-3_12	arangodb/enterprise-preview:devel-nightly
string	generators	metrics error-codes exit-codes optimizer options
boolean	commit-generated	true
boolean	create-pr	true
string	pr-branch	scheduled-content-generate_$CIRCLE_BUILD_NUM

Similarly, the generate-oasisctl workflow is automatically triggered and repeats on the 5th of every month. It generates pages about the command-line interface of the tool.

Invoke Args:

Parameter type	Name	Value
string	workflow	generate-oasisctl
string	generators	oasisctl
boolean	commit-generated	true
boolean	create-pr	true
string	pr-branch	scheduled-oasisctl-generate_$CIRCLE_BUILD_NUM

Both workflows can be manually triggered in the CircleCI web interface via Trigger Pipeline.

Other workflows

Create Docs Images AMD64

Parameter type	Name	Value
string	workflow	create-docs-images-amd64

Create Docs Images ARM64

Parameter type	Name	Value
string	workflow	create-docs-images-arm64