8.6 KiB

Raw Blame History

Release process

Only for Maintainers.

Decide the component(s) and tag name (version name) to be released. We use MinVer to do versioning, which produces version numbers based on git tags.

Notes:
- There are different categories of packages. Check the project file for what you want to release and look for MinVerTagPrefix.
  - core-: Core packages. These packages are defined\goverened by the OpenTelemetry Specification or are part of fundamental infrastructure and have released stable versions. They may be released as alpha, beta, rc, or stable.
    - OpenTelemetry.Api - Defined by spec (API)
    - OpenTelemetry.Api.ProviderBuilderExtensions - Fundamental infrastructure
    - OpenTelemetry - Defined by spec (SDK)
    - OpenTelemetry.Exporter.Console - Defined by spec
    - OpenTelemetry.Exporter.InMemory - Defined by spec
    - OpenTelemetry.Exporter.OpenTelemetryProtocol - Defined by spec
    - OpenTelemetry.Exporter.Zipkin - Defined by spec
    - OpenTelemetry.Extensions.Hosting - Fundamental infrastructure
    - OpenTelemetry.Extensions.Propagators - Defined by spec
  - coreunstable-: Core unstable packages. These packages are defined\goverened by the OpenTelemetry Specification or are part of fundamental infrastructure but have not released stable versions. As of the 1.9.0 release cycle they may only be released as alpha or beta.
    - OpenTelemetry.Exporter.Prometheus.AspNetCore - Defined by spec (experimental)
    - OpenTelemetry.Exporter.Prometheus.HttpListener - Defined by spec (experimental)
    - OpenTelemetry.Shims.OpenTracing - Defined by spec (stable but incomplete implementation)
- As of the 1.9.0 release cycle instrumentation packages and core unstable packages always depend on the stable versions of core packages. Before releasing a non-core component ensure the OTelLatestStableVer property in Directory.Packages.props has been updated to the latest stable core version.
Prepare for release

Run the Prepare for a release workflow. Specify the tag-prefix and the version for the release. Make sure to run the workflow on the branch being released. This is typically main but could be some other branch for hotfix (eg main-1.8.0). The workflow will open a PR to update CHANGELOG.md files for the projects being released. If a stable version is specified as the version parameter, the workflow will also merge the contents of any detected PublicAPI.Unshipped.txt files in the .publicApi folder into the corresponding PublicAPI.Shipped.txt files for the projects being released.
Instructions for preparing for a release manually
- Update CHANGELOG files
  
  Run the PowerShell script .\build\scripts\update-changelogs.ps1 -minVerTagPrefix [MinVerTagPrefix] -version [Version]. Where [MinVerTagPrefix] is the tag prefix (eg core-) for the components being released and [Version] is the version being released (eg 1.9.0). This will update CHANGELOG.md files for the projects being released.
- Stable releases only: Normalize PublicApi files
  
  Run the PowerShell script .\build\scripts\finalize-publicapi.ps1 -minVerTagPrefix [MinVerTagPrefix]. Where [MinVerTagPrefix] is the tag prefix (eg core-) for the components being released. This will merge the contents of any detected PublicAPI.Unshipped.txt files in the .publicApi folder into the corresponding PublicAPI.Shipped.txt files for the projects being released.
🛑 The PR opened by Prepare for a release workflow in step 2 has to be merged.
Once the PR opened by Prepare for a release workflow in step 2 has been merged a trigger will automatically add a comment and lock the PR. Post a comment with "/CreateReleaseTag" in the body. This will tell the Prepare for a release workflow to push the tag for the merge commit of the PR and to call the Build, pack, and publish to MyGet workflow. Once packages are available a comment will be posted on the PR opened in step 2 with a link to the artifacts.
Instructions for pushing tags manually

Note: In the below examples git push origin is used. If running in a fork, add the main repo as upstream and use git push upstream instead. Pushing a tag to origin in a fork pushes the tag to the fork.
- If releasing core components, add and push the tag prefixed with core-. For example:
```
git tag -a core-1.4.0-beta.1 -m "1.4.0-beta.1 of all core components"
git push origin core-1.4.0-beta.1
```
- If releasing core unstable components, push the tag prefixed with coreunstable-. For example:
```
git tag -a coreunstable-1.9.0-beta.1 -m "1.9.0-beta.1 of all core unstable components"
git push origin coreunstable-1.9.0-beta.1
```
Pushing the tag will kick off the Build, pack, and publish to MyGet workflow.
🛑 Wait for the Build, pack, and publish to MyGet workflow to complete.
Validate locally everything works using the MyGet packages pushed from the release. Basic sanity checks :)
Download the artifacts from the drop attached to the workflow run. The artifacts archive (.zip) contains all the NuGet packages (.nupkg) and symbols (.snupkg) from the build which were pushed to MyGet.
Extract the artifacts from the archive (.zip) into a local folder.
Download latest nuget.exe into the same folder from Step 8.
Create or regenerate an API key from nuget.org (only maintainers have access). When creating API keys make sure it is set to expire in 1 day or less.

Run the following commands from PowerShell from local folder used in Step 8:

.\nuget.exe setApiKey <actual api key>

get-childitem -Recurse | where {$_.extension -eq ".nupkg"} | foreach ($_) {.\nuget.exe push $_.fullname -Source https://api.nuget.org/v3/index.json}

Validate that the package(s) are uploaded. Packages are available immediately to maintainers on nuget.org but aren't publicly visible until scanning completes. This process usually takes a few minutes.
Open the Releases page on the GitHub repository. The Build, pack, and publish to MyGet workflow creates a draft release for the tag which was pushed. Edit the draft Release and click Publish release.
If a new stable version of the core packages was released, a draft PR should have been automatically created by the Build, pack, and publish to MyGet workflow to update the OTelLatestStableVer property in Directory.Packages.props to the just released stable version. Mark that PR Ready for review and then merge it once the build passes (this requires the packages be available on NuGet).
If a new stable version of the core packages was released, open an issue in the opentelemetry-dotnet-contrib repo to notify maintainers to begin upgrading dependencies.
Post an announcement in the Slack channel. Note any big or interesting new features as part of the announcement.

8.6 KiB Raw Blame History

Release process

8.6 KiB

Raw Blame History