Skip to content

feat: pin library defaults for v2 #19

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.

Sign up for GitHub

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

Merged
juan-fernandez merged 2 commits into from
Jul 16, 2026
Merged

feat: pin library defaults for v2 #19

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
e84c5e9
feat: pin library defaults for v2
juan-fernandez Jul 15, 2026
167fe35
fix: validate release PR labels
juan-fernandez Jul 15, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions .github/workflows/release.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,5 +17,7 @@ jobs:
uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
- name: Release
uses: softprops/action-gh-release@153bb8e04406b158c6c84fc1615b65b24149a1fe # v2.6.1
with:
generate_release_notes: true
env:
GITHUB_TOKEN: ${{ secrets.RELEASE_ACCESS_TOKEN }}
66 changes: 58 additions & 8 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ It can help you investigate and mitigate performance problems and test failures
version: 2.1

orbs:
test-optimization-circleci-orb: datadog/test-optimization-circleci-orb@1
test-optimization-circleci-orb: datadog/test-optimization-circleci-orb@2

jobs:
test:
Expand All @@ -33,6 +33,34 @@ jobs:
- run: pytest
```

### Choose an orb version

Starting with v2, each orb release pins its default library versions instead of resolving the latest versions during customer runs. [CircleCI registry orbs use semantic version references](https://circleci.com/docs/orbs/use/orb-concepts/#semantic-versioning-registry-orbs), so the value after `@` determines whether a workflow receives newer orb releases and their reviewed library snapshots:

| Reference | Example | Behavior | Trade-off |
| --------- | ------- | -------- | --------- |
| Moving major | `datadog/test-optimization-circleci-orb@2` | Receives reviewed compatible v2 releases, including library bumps. It does not move to v3. | The orb behavior and default libraries can change when a new v2 release is published. |
| Exact release | `datadog/test-optimization-circleci-orb@2.0.0` | Keeps the selected immutable production orb code and default library snapshot stable. | Requires an explicit update to receive fixes and library bumps. |

These references select the orb release and its default library snapshot. To hold one library at a specific version independently of the orb reference, [set its version parameter explicitly](#pin-an-individual-library-version).

For most workflows, `@2` is the simplest way to receive compatible, reviewed updates. Use `@2.0.0` when the orb and its defaults must remain fixed until the configuration is updated explicitly.

### Migrate from v1 to v2

The `@1` reference does not move to v2 automatically. Update the orb declaration in each CircleCI configuration you want to migrate:

```diff
- test-optimization-circleci-orb: datadog/test-optimization-circleci-orb@1
+ test-optimization-circleci-orb: datadog/test-optimization-circleci-orb@2
```

No parameter names or required configuration change. Omitted library-version parameters use the pinned v2 snapshot listed in the [configuration table](#configuration), so the first v2 run may use different libraries from the last v1 run. Those defaults no longer change independently on every run.

Explicit library-version parameters remain authoritative. With `@2`, reviewed v2 releases can update the orb and any omitted library defaults; with `@2.0.0`, the orb and its default snapshot remain fixed until the reference is updated explicitly.

Before migrating, review the v2 defaults and run a representative workflow. Set an explicit version parameter first if a workflow must keep using a validated library version.

## Configuration

The orb has the following parameters:
Expand All @@ -42,15 +70,37 @@ The orb has the following parameters:
| languages | List of languages to be instrumented. Can be either "all" or any of "java", "js", "python", "dotnet", "ruby" (multiple languages can be specified as a space-separated list). | true | |
| site | Datadog site. See https://docs.datadoghq.com/getting_started/site for more information about sites. | false | datadoghq.com |
| service | The name of the service or library being tested. | false | |
| dotnet_tracer_version | The version of Datadog .NET tracer to use. Defaults to the latest release. | false | |
| java_tracer_version | The version of Datadog Java tracer to use. Defaults to the latest release. | false | |
| js_tracer_version | The version of Datadog JS tracer to use. Defaults to the latest release. | false | |
| python_tracer_version | The version of Datadog Python tracer to use. Defaults to the latest release. | false | |
| ruby_tracer_version | The version of datadog-ci gem to use. Defaults to the latest release. | false | |
| go_tracer_version | The version of Orchestrion automatic compile-time instrumentation of Go code (https://github.com/datadog/orchestrion) to use. Defaults to the latest release. | false | |
| python_coverage_version | The version of the Python `coverage` package to use. Defaults to `7.13.5`. | false | |
| dotnet_tracer_version | The version of Datadog .NET tracer to use. | false | 3.49.0 |
| java_tracer_version | The version of Datadog Java tracer to use. | false | 1.64.0 |
| js_tracer_version | The version of Datadog JS tracer to use. | false | 6.3.0 |
| python_tracer_version | The version of Datadog Python tracer to use. | false | 4.11.0 |
| ruby_tracer_version | The version of datadog-ci gem to use. | false | 1.34.0 |
| go_tracer_version | The version of Orchestrion automatic compile-time instrumentation of Go code (https://github.com/datadog/orchestrion) to use. | false | v1.11.0 |
| python_coverage_version | The version of the Python `coverage` package to use. | false | 7.15.1 |
| java_instrumented_build_system | If provided, only the specified build systems will be instrumented (allowed values are `gradle`,`maven`,`sbt`,`ant`,`all`). `all` is a special value that instruments every Java process. If this property is not provided, all known build systems will be instrumented (Gradle, Maven, SBT, Ant). | false | |

### Pin an individual library version

Set a library's version parameter to override the default selected by the orb release. The explicit version remains fixed when a moving major reference advances:

```yaml
orbs:
test-optimization-circleci-orb: datadog/test-optimization-circleci-orb@2

jobs:
test:
docker:
- image: eclipse-temurin:17
steps:
- test-optimization-circleci-orb/autoinstrument:
languages: java
java_tracer_version: 1.64.0
```

This allows orb updates while holding a library at a version you have validated. The explicit parameter overrides the orb release default, remains fixed when `@2` advances, and must be updated manually to receive future fixes for that library. The same behavior applies to every library-version parameter in the table above.

Maintainers can use the local scripts described in [RELEASE.md](RELEASE.md) to create a batched library bump PR and publish the resulting orb release.

### Additional configuration

Any [additional configuration values](https://docs.datadoghq.com/tracing/trace_collection/library_config/) can be added directly to the job that runs your tests:
Expand Down
91 changes: 91 additions & 0 deletions RELEASE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,91 @@
# Release Process

This repository publishes immutable semantic versions of a CircleCI registry orb, such as `2.0.0`. Git tags use the corresponding `v2.0.0` form and trigger the existing Orb Tools production publishing workflow.

## Requirements

The local maintenance scripts require `curl`, `git`, `gh`, and Ruby. Authenticate the GitHub CLI before using them:

```bash
gh auth login
gh auth status
```

Scripts that create commits use signed commits and verify the signature before pushing. Run the bump PR and release helpers from a clean working tree.

## Release labels

Every PR intended for a release must have one of these labels:

- `semver-patch`: requests the next patch release
- `semver-minor`: requests the next minor release
- `semver-major`: requests the next major release

If a release includes multiple merged PRs, the highest requested version change wins. An explicit tag can also be supplied to the release script.

## Bump pinned library versions

Use `scripts/create-library-version-bump-pr.sh` for the normal maintainer workflow. It discovers available updates and handles the branch, signed commit, push, labels, and PR.

Preview all currently available library updates:

```bash
scripts/create-library-version-bump-pr.sh --dry-run
```

Create one PR containing every available update:

```bash
scripts/create-library-version-bump-pr.sh
```

The script reads the official package sources for .NET, Java, JavaScript, Python, Python coverage, Ruby, and Go/Orchestrion. If at least one pinned default is outdated, it updates `src/commands/autoinstrument.yml` and `README.md`, creates and verifies a signed commit, pushes the branch, and opens a PR. The PR lists exactly which languages changed so release notes remain relevant to users of those languages.

The PR receives:

- `library-version-bump`
- `semver-patch` when every update is a patch
- `semver-minor` when at least one library changes its major or minor version

Use `scripts/bump-library-versions.sh` only as the lower-level manual tool for targeted changes or testing. It accepts explicit versions and updates the orb source and README without querying package sources, creating a branch or commit, pushing, or opening a PR.

```bash
scripts/bump-library-versions.sh --java 1.65.0 --js 6.3.1
scripts/bump-library-versions.sh --go v1.12.0
```

Review and merge the resulting changes normally.

## Release the orb

Preview the next release first:

```bash
scripts/release-orb.sh --dry-run
```

The script fetches `main` and release tags, finds merged PRs since the latest immutable release, reads their `semver-patch`, `semver-minor`, and `semver-major` labels, and selects the highest release level. It verifies the release commit's signature and creates only the immutable `vX.Y.Z` tag. It never creates or moves a `v2` Git branch; CircleCI resolves `@2` through the orb registry after the tag-triggered Orb Tools workflow publishes the production version.

Publish the inferred release:

```bash
scripts/release-orb.sh
```

Release a specific commit on `main`:

```bash
scripts/release-orb.sh --sha abc1234 --dry-run
scripts/release-orb.sh --sha abc1234
```

Choose the tag explicitly:

```bash
scripts/release-orb.sh --tag v2.0.0 --dry-run
scripts/release-orb.sh --tag v2.0.0
```

If the requested tag is lower than the merged PR labels imply, the script fails. To publish that tag intentionally, pass `--allow-version-mismatch` with `--tag`.

After the tag is pushed, the CircleCI workflow tests and publishes the production orb version. The GitHub release workflow creates release notes from the merged PRs, including the affected-language details from library bump PRs.
107 changes: 107 additions & 0 deletions scripts/bump-library-versions.sh
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,107 @@
#!/usr/bin/env bash
set -euo pipefail

usage() {
cat <<'EOF'
Usage: scripts/bump-library-versions.sh [OPTIONS]

Updates one or more pinned library versions in
src/commands/autoinstrument.yml and README.md.

Options:
--dotnet VERSION Datadog .NET tracer version
--java VERSION Datadog Java tracer version
--js VERSION Datadog JavaScript tracer version
--python VERSION Datadog Python tracer version
--coverage VERSION Python coverage version
--ruby VERSION datadog-ci Ruby gem version
--go VERSION Orchestrion version, including the leading v
-h, --help Show this help
EOF
}

updates=()
while [[ $# -gt 0 ]]; do
case "$1" in
-h|--help)
usage
exit 0
;;
--dotnet|--java|--js|--python|--coverage|--ruby|--go)
if [[ -z "${2:-}" ]]; then
usage >&2
exit 1
fi
updates+=("${1#--}=$2")
shift 2
;;
*)
usage >&2
exit 1
;;
esac
done

if [[ ${#updates[@]} -eq 0 ]]; then
usage >&2
exit 1
fi

if ! command -v ruby >/dev/null 2>&1; then
echo "Missing required command: ruby" >&2
exit 1
fi

ruby - "${updates[@]}" <<'RUBY'
parameter_names = {
'dotnet' => 'dotnet_tracer_version',
'java' => 'java_tracer_version',
'js' => 'js_tracer_version',
'python' => 'python_tracer_version',
'coverage' => 'python_coverage_version',
'ruby' => 'ruby_tracer_version',
'go' => 'go_tracer_version'
}.freeze

parsed_updates = ARGV.map do |argument|
name, version = argument.split('=', 2)
abort "Unknown library '#{name}'" unless parameter_names.key?(name)
abort "Missing version for '#{name}'" if version.nil? || version.empty?

expected_pattern = name == 'go' ? /^v\d+\.\d+\.\d+$/ : /^\d+\.\d+\.\d+$/
abort "Expected an exact #{name} version, got '#{version}'" unless version.match?(expected_pattern)

[name, version]
end
updates = parsed_updates.to_h

abort 'Each library may only be specified once' unless updates.length == parsed_updates.length

orb_path = 'src/commands/autoinstrument.yml'
readme_path = 'README.md'
orb = File.read(orb_path)
readme = File.read(readme_path)

updates.each do |name, version|
parameter_name = parameter_names.fetch(name)
orb_pattern = /(^ #{Regexp.escape(parameter_name)}:\n(?:(?!^ [A-Za-z0-9_]+:).*\n)*?^ default: )'[^']+'/
abort "Unable to find #{parameter_name} default in #{orb_path}" unless orb.scan(orb_pattern).length == 1
orb.sub!(orb_pattern) { "#{Regexp.last_match(1)}'#{version}'" }

readme_pattern = /^(\| #{Regexp.escape(parameter_name)}\s+\|[^|]*\|[^|]*\|)([^|]*)(\|)$/
match = readme.match(readme_pattern)
abort "Unable to find #{parameter_name} default in #{readme_path}" unless match

default_cell = " #{version} "
abort "Version '#{version}' does not fit in the README default column" if default_cell.length > match[2].length

readme.sub!(readme_pattern) do
"#{Regexp.last_match(1)}#{default_cell.ljust(Regexp.last_match(2).length)}#{Regexp.last_match(3)}"
end

puts "Updated #{parameter_name} to #{version}"
end

File.write(orb_path, orb)
File.write(readme_path, readme)
RUBY
Loading