-
Notifications
You must be signed in to change notification settings - Fork 4
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
chore: add release docs + general docs cleanup and polish #491
Merged
Merged
Changes from all commits
Commits
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,3 +1,3 @@ | ||
| Datadog Saluki | ||
| Copyright 2024-Present Datadog, Inc. | ||
| This product includes software developed at Datadog (<https://www.datadoghq.com/).> | ||
| This product includes software developed at Datadog (<https://www.datadoghq.com/>). |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
File renamed without changes.
File renamed without changes.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,93 @@ | ||
| # Releasing Saluki / Agent Data Plane | ||
|
|
||
| This document describes the process of releasing new versions of Saluki and Agent Data Plane. | ||
|
|
||
| ## Saluki | ||
|
|
||
| At this time (2025-02-11), Saluki is not yet officially released. This means that all usages of Saluki are driven either | ||
| through pointing directly at the repository (using a specific branch, tag, or commit hash), or utilizing path-based | ||
| dependencies, such as is done in Agent Data Plane. | ||
|
|
||
| ## Agent Data Plane | ||
|
|
||
| Agent Data Plane has official releases which show up in two forms: | ||
|
|
||
| - tagged releases that are exposed through Github Releases | ||
| - matching container image builds that are pushed to public container image repositories | ||
|
|
||
| Agent Data Plane is a data plane built on Saluki, which is meant to operate in tandem with the Datadog Agent. This means | ||
| that while we build ADP from the Saluki repository in a standalone way, we couple it to a specific version of the | ||
| Datadog Agent, including the container image that we publish. | ||
|
|
||
| ### Quick steps | ||
|
|
||
| - Ensure that `main` is up-to-date with all of the intended changes that should be present, and that CI tests are | ||
| passing cleanly (this will get checked in the actual release CI pipeline, but easier to catch problems early) | ||
| - Go to the [Releases](https://github.com/DataDog/saluki/releases) page on Github and click the `Draft a new release` | ||
| button. | ||
| - Fill in the appropriate version tag (see "Determining the version" below) and click `Create new tag ... on publish`. | ||
| - Leave `Previous tag` at `auto`, and change `Release title` to `Agent Data Plane <version>`, where `<version>` is the | ||
| new version. (i.e., `Agent Data Plane 0.2.0`) | ||
| - Click the `Generate release notes` to automatically populate the relevant changes since the last release. | ||
| - If there are any additional notes that should be included, add a new section, called `Additional Notes`, at the top of | ||
| the release notes (above the auto-generated `What's Changed` section) | ||
| - Click `Publish release` | ||
| - Go to the [Gitlab CI pipelines dashboard](https://gitlab.ddbuild.io/DataDog/saluki/-/pipelines) for the repository and | ||
| find the pipeline that was triggered for the newly-created Git tag. It may take a minute or two for the repository | ||
| sync and pipeline creation to occur. | ||
| - The pipeline should progress through the `test`, `build`, `correctness`, `benchmark`, and `release` stages without | ||
| issue. | ||
| - Once all stages have completed, the `release` stage will have two blocked jobs: `publish-bundled-agent-adp-image` and | ||
| `publish-bundled-agent-adp-image-jmx`. These jobs perform the actual publishing of the container images to our public | ||
| container image registries, and must be manually triggered. | ||
| - Once triggered, they should run to completion. | ||
| - Once complete, you should be able to navigate to a public container image registry that we use, such as [Docker | ||
| Hub](https://hub.docker.com/r/datadog/agent/tags), and find the resulting images: if the tag was `0.2.0`, you should | ||
| be able to see a recently-published image with a tag that looks like `<Agent version>-v0.2.0-adp-beta-jmx`. (See | ||
| "Determining the version" below for more information on the container image tag format.) | ||
|
|
||
| ### Determining the version | ||
|
|
||
| For ADP, we determine the version of the release solely from the Git tag that is created, which also drives the CI | ||
| pipeline used to publish the resulting container images. We _do not_ use the `version` field of the `agent-data-plane` | ||
| crate itself. | ||
|
|
||
| When deciding what version to use, we follow the [Semantic Versioning](https://semver.org/) specification. This means, | ||
| in a nutshell: | ||
|
|
||
| - prior to v1.0.0: | ||
| * breaking changes are indicated by incrementing the minor version | ||
| * new features and bug fixes are generally indicated by incrementing the patch version | ||
| * if there are enough new features/bug fixes, we may instead opt to increment the minor version just for simplicity | ||
| - after v1.0.0: | ||
| * breaking changes are indicated by incrementing the major version (this should generally never happen after v1) | ||
| * new features are indicated by incrementing the minor version | ||
| * bug fixes are indicated by incrementing the patch version | ||
|
|
||
| Additionally, for the container images we build, there is an additional component in the image tag that specifies the | ||
| version of the Datadog Agent that the image is based on. The Datadog Agent version is controlled in `.gitlab-ci.yml`, via the `BASE_DD_AGENT_VERSION` | ||
| variable. We pull the Datadog Agent image from a public container image registry (Google Container Registry) and layer | ||
| on the ADP binary, and supporting files, which results in our final "bundled" ADP container image. | ||
|
|
||
| ### Build metadata | ||
|
|
||
| We calculate a number of values that are used to populate what we call "build metadata", which is information passed in | ||
| during the build process and is used to drive a number of behaviors: | ||
|
|
||
| - outputting the version of ADP, when it was built, the build architecture, etc, as a log at startup | ||
| - special constant identifiers that are used to populate things like HTTP request headers (user agent, etc) | ||
|
|
||
| This build metadata is _normally_ calculated with a Make target -- `emit-build-metadata` -- which populates it during | ||
| local builds or regular CI builds. However, for release builds, it is set manually when invoking the container image | ||
| builds. These settings can be found in the `.gitlab/release.yml` file, under the `build-release-adp-image` job. | ||
|
|
||
| The relevant build arguments are all prefixed with `APP_` and are as follows: | ||
|
|
||
| - `APP_FULL_NAME`: the full name of the application (hard-coded to `agent-data-plane`) | ||
| - `APP_SHORT_NAME`: the short name of the application (hard-coded to `data-plane`) | ||
| - `APP_IDENTIFIER`: a short identifier for the application (hard-coded to `adp`) | ||
| - `APP_VERSION`: the version of the application (set to the Git tag) | ||
| - `APP_BUILD_DATE`: the date the build was performed (set to the creation time of the Gitlab CI pipeline) | ||
|
|
||
| This build metadata should not need to be manually changed on a per-release basis, and so this section is mostly | ||
| informational and not relevant to the release process itself. | ||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Some projects put this in VERSIONING.md so people may expect to find it there. You could create that doc and just point to here or vice versa.
Example: https://github.com/open-telemetry/opentelemetry-go/blob/main/VERSIONING.md
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'll definitely consider that as a follow-up improvement.