Each Jaeger version is documented in a separate directory e.g. content/docs/1.8/. A special directory content/docs/next-release/ is reserved for the changes to be published as the next version. If you are adding documentation for features that are not yet released in the main Jaeger repository, add your changes to the next-release directory. If you're adding documentation for already released features, you may need to make the same change twice, i.e. in the most recent release (e.g. 1.8) and in the next-release directories.
Jaeger v2 next-release documentation is in the next-release-v2 directory.
Before creating a new release:
- Make sure all outstanding PRs for that version are merged to
next-releasedirectory. - Make sure the actual Jaeger release is done and Docker images for the new version are published.
- If there are new Jaeger binaries or new storage options added to the release, make sure the CLI docs config file
data/cli/next-release/config.jsonis updated accordingly (see below).
To create a new release:
- Manually trigger the Release workflow on GitHub. It will ask for v1 and v2 version numbers (same versions as in the main Jaeger repo), and create a pull request with the documentation changes.
- Approve and merge that pull request.
- Because the site is statically generated, the release is completed after the merge.
The docs for the Jaeger CLI tools are generated by the automated release process described above using the Python script scripts/gen-cli-data.py. It uses the configuration file data/cli/next-release/config.json (automatically copied to data/cli/${NEXT_VERSION}/config.json) that describes which Jaeger binaries to include in the documentation, and which storage options each binary supports. The script invokes the docs command on the respective Docker images for each binary and creates a set of YAML files under data/cli/${NEXT_VERSION}/, which are then used by the template engine to render the CLI docs.