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. Theplain-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} |
To update the live documentation independently of an ArangoDB release, for example, because of changes to the ArangoGraph docs or to publish documentation improvements before the next ArangoDB release, follow the steps below.
- Go to CircleCI and select the
docs-hugo
project. - Select the
main
branch. - Click the Trigger Pipeline button.
- Add the parameters described below.
- 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.arangodb.com without approval step.
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.
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} |
workflow
:commit-generated
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 |
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 | generators |
examples |
boolean | commit-generated |
true |
string | deploy-url |
deploy-preview-{PR_NUMBER} |
string | override |
http,^aql.* |
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.
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.
- Go to CircleCI and select the
docs-hugo
project. - Select the
main
branch. - Click the Trigger Pipeline button.
- Add the parameters described below.
- 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.arangodb.com
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.
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 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 | 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 |
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.
Parameter type | Name | Value |
---|---|---|
string | workflow |
create-docs-images-amd64 |
Parameter type | Name | Value |
---|---|---|
string | workflow |
create-docs-images-arm64 |