[repo] Define release process for unstable core components (#5531)

open-telemetry · Apr 17, 2024 · 3898df5 · 3898df5
1 parent 1fb00d9
commit 3898df5
Show file tree

Hide file tree

Showing 15 changed files with 211 additions and 73 deletions.
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -34,6 +34,7 @@ jobs:
           instrumentation-packages: ['src/OpenTelemetry.Instrumentation*/**', '!**/*.md']
           sdk-code: ['src/OpenTelemetry/**', 'test/OpenTelemetry.Tests/**', '!**/*.md']
           sdk-package: ['src/OpenTelemetry/**', '!**/*.md']
+          unstable-core-packages: ['src/OpenTelemetry.Exporter.Prometheus.AspNetCore/**', 'src/OpenTelemetry.Exporter.Prometheus.HttpListener/**', 'src/OpenTelemetry.Shims.OpenTracing/**', '!**/*.md']
           otlp: ['*/OpenTelemetry.Exporter.OpenTelemetryProtocol*/**', '!**/*.md']
 
   lint-md:
@@ -100,6 +101,19 @@ jobs:
       project-build-commands: '-p:RunningDotNetPack=true -p:ExposeExperimentalFeatures=true'
       code-cov-name: 'Instrumentation-Experimental'
 
+  # Build unstable core libraries using stable packages released to NuGet
+  build-test-unstable-core:
+    needs: detect-changes
+    if: |
+      contains(needs.detect-changes.outputs.changes, 'unstable-core-packages')
+      || contains(needs.detect-changes.outputs.changes, 'build')
+      || contains(needs.detect-changes.outputs.changes, 'shared')
+    uses: ./.github/workflows/Component.BuildTest.yml
+    with:
+      project-name: './build/UnstableCoreLibraries.proj'
+      project-build-commands: '-p:RunningDotNetPack=true -p:ExposeExperimentalFeatures=true'
+      code-cov-name: 'Unstable-Core'
+
   otlp-integration-test:
     needs: detect-changes
     if: |
@@ -180,6 +194,7 @@ jobs:
       build-test-solution-experimental,
       build-test-instrumentation-stable,
       build-test-instrumentation-experimental,
+      build-test-unstable-core,
       otlp-integration-test,
       w3c-trace-context-integration-test,
       validate-packages,

diff --git a/.github/workflows/package-validation.yml b/.github/workflows/package-validation.yml
@@ -21,7 +21,7 @@ jobs:
       uses: actions/setup-dotnet@v4
 
     - name: Pack
-      run: dotnet pack OpenTelemetry.proj --configuration Release /p:EnablePackageValidation=true /p:ExposeExperimentalFeatures=false
+      run: dotnet pack OpenTelemetry.proj --configuration Release /p:EnablePackageValidation=true /p:ExposeExperimentalFeatures=false /p:RunningDotNetPack=true
 
   run-package-validation-experimental:
     runs-on: windows-latest
@@ -38,4 +38,4 @@ jobs:
       uses: actions/setup-dotnet@v4
 
     - name: Pack
-      run: dotnet pack OpenTelemetry.proj --configuration Release /p:EnablePackageValidation=true /p:ExposeExperimentalFeatures=true
+      run: dotnet pack OpenTelemetry.proj --configuration Release /p:EnablePackageValidation=true /p:ExposeExperimentalFeatures=true /p:RunningDotNetPack=true
diff --git a/.github/workflows/publish-packages-1.0.yml b/.github/workflows/publish-packages-1.0.yml
@@ -36,7 +36,7 @@ jobs:
       run: dotnet build OpenTelemetry.proj --configuration Release --no-restore -p:Deterministic=true -p:BuildNumber=${{ github.run_number }} -p:RunningDotNetPack=true
 
     - name: dotnet pack
-      run: dotnet pack OpenTelemetry.proj --configuration Release --no-restore --no-build
+      run: dotnet pack OpenTelemetry.proj --configuration Release --no-restore --no-build -p:PackTag=${{ github.ref }}
 
     - name: Publish Artifacts
       uses: actions/upload-artifact@v4

diff --git a/OpenTelemetry.sln b/OpenTelemetry.sln
@@ -36,6 +36,7 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "build", "build", "{7CB2F02E
 		build\docker-compose.net8.0.yml = build\docker-compose.net8.0.yml
 		build\finalize-publicapi.ps1 = build\finalize-publicapi.ps1
 		build\GlobalAttrExclusions.txt = build\GlobalAttrExclusions.txt
+		build\InstrumentationLibraries.proj = build\InstrumentationLibraries.proj
 		build\opentelemetry-icon-color.png = build\opentelemetry-icon-color.png
 		build\OpenTelemetry.prod.loose.ruleset = build\OpenTelemetry.prod.loose.ruleset
 		build\OpenTelemetry.prod.ruleset = build\OpenTelemetry.prod.ruleset
@@ -46,6 +47,7 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "build", "build", "{7CB2F02E
 		build\test-aot-compatibility.ps1 = build\test-aot-compatibility.ps1
 		build\test-threadSafety.ps1 = build\test-threadSafety.ps1
 		build\xunit.runner.json = build\xunit.runner.json
+		build\UnstableCoreLibraries.proj = build\UnstableCoreLibraries.proj
 	EndProjectSection
 EndProject
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "OpenTelemetry.Exporter.Zipkin", "src\OpenTelemetry.Exporter.Zipkin\OpenTelemetry.Exporter.Zipkin.csproj", "{7EDAE7FA-B44E-42CA-80FA-7DF2FAA2C5DD}"

diff --git a/build/Common.prod.props b/build/Common.prod.props
@@ -54,6 +54,10 @@
       <ExposeExperimentalFeatures Condition="'$(MinVerPreRelease)' == ''">false</ExposeExperimentalFeatures>
     </PropertyGroup>
 
+    <Error
+      Condition="'$(MinVerTagPrefix)' == 'coreunstable-' AND ('$(MinVerPreRelease)' == '' OR $(MinVerPreRelease.StartsWith('rc')))"
+      Text="Unstable core packages cannot be released stable or as release candidates." />
+
     <!-- Note: The '$(TargetFramework)' != '' check here is to reduce log spam
     in builds like dotnet pack which fire MinVer but don't resolve the actual
     TargetFramework -->
@@ -63,6 +67,12 @@
       Text="**AssemblyVersionDebug** TargetFramework: $(TargetFramework), MinVerVersion: $(MinVerVersion), BuildNumber: $(BuildNumber), FileVersion: $(FileVersion), ExposeExperimentalFeatures: $(ExposeExperimentalFeatures)" />
   </Target>
 
+  <Target Name="EnsurePackageValidationBaselineVersion"
+          BeforeTargets="RunPackageValidation"
+          Condition="'$(DisablePackageBaselineValidation)' != 'true' AND '$(PackageValidationBaselineVersion)' == '' AND '$(MinVerTagPrefix)' != 'coreunstable-'">
+    <Error Text="Cannot perform package validation without a baseline package version." />
+  </Target>
+
   <Target Name="ResolveExposeExperimentalFeatures" BeforeTargets="CoreCompile" DependsOnTargets="AssemblyVersionTarget">
     <!-- Note: This runs for all builds. The goal here is to set the
     EXPOSE_EXPERIMENTAL_FEATURES compiler constant if

diff --git a/build/RELEASING.md b/build/RELEASING.md
@@ -1,9 +1,61 @@
 # Release process
 
-Only for Maintainers.
-
- 1. Decide the tag name (version name) to be released. e.g. 1.4.0-beta.1,
-    1.0.0-rc9.7 etc.
+**Only for Maintainers.**
+
+ 1. Decide the component(s) and tag name (version name) to be released.
+
+    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)
+
+         * Everything else: Instrumentation packages have dedicated tags. Some
+           packages have released stable and some have not. These packages may
+           be released as `alpha`, `beta`, `rc`, or stable depending on the
+           stability of the semantic conventions used by the instrumentation.
+
+           * Stable:
+             * `OpenTelemetry.Instrumentation.AspNetCore` (`Instrumentation.AspNetCore-`)
+             * `OpenTelemetry.Instrumentation.Http` (`Instrumentation.Http-`)
+
+           * Unstable:
+             * `OpenTelemetry.Instrumentation.GrpcNetClient` (`Instrumentation.GrpcNetClient-`)
+             * `OpenTelemetry.Instrumentation.SqlClient` (`Instrumentation.SqlClient-`)
+
+       * 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.
 
  2. Run the following PowerShell from the root of the repo to get combined
     changelog (to be used later).
@@ -62,80 +114,97 @@ Only for Maintainers.
     `.\build\finalize-publicapi.ps1`. This will merge the contents of
     Unshipped.txt into the Shipped.txt.
 
- 5. Submit PR with the above changes, and get it merged.
+ 5. The scripts in steps 2-4 run over the entire repo. Remove and undo changes
+    under projects which are not being released. Submit a PR with the final
+    changes and get it merged.
 
  6. Tag Git with version to be released. We use
     [MinVer](https://github.com/adamralph/minver) to do versioning, which
     produces version numbers based on git tags.
 
-    Note: If releasing only core components, only add and push the tag prefixed
-    with `core-`. For example:
+    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.
 
-    ```sh
-    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 components, add and push the tag prefixed with `core-`.
+    For example:
 
-    If releasing only non-core components, only add and push the tags without
-    prefix. For example:
+       ```sh
+       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
+       ```
 
-    ```sh
-    git tag -a 1.0.0-rc9.7 -m "1.0.0-rc9.7 of all non-core components"
-    git push origin 1.0.0-rc9.7
-    ```
+    * If releasing core unstable components, push the tag prefixed with
+    `coreunstable-`. For example:
 
-    If releasing only a particular non-core component which has a dedicated
-    MinverTagPrefix such as AspNetCore instrumentation, only add and push the
-    tag with that particular prefix. For example:
+       ```sh
+       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
+       ```
 
-    ```sh
-    git tag -a Instrumentation.AspNetCore-1.6.0 -m "1.6.0 of AspNetCore instrumentation library"
-    git push origin Instrumentation.AspNetCore-1.6.0
-    ```
+    * If releasing a particular non-core component which has a dedicated
+    `MinverTagPrefix` (such as AspNetCore instrumentation), push the tag with
+    that particular prefix. For example:
 
-    If releasing multiple kinds of components, push both tags for each of them.
+       ```sh
+       git tag -a Instrumentation.AspNetCore-1.6.0 -m "1.6.0 of AspNetCore instrumentation library"
+       git push origin Instrumentation.AspNetCore-1.6.0
+       ```
 
  7. Go to the [list of
-    tags](https://github.com/open-telemetry/opentelemetry-dotnet/tags)
-    and find the tag created for the core components. Click the three
-    dots next to the tag and choose `Create release`.
-      * Give the release a name based on the tags created
-      (e.g., `1.4.0-beta.1 / 1.0.0-rc9.7`).
-      * Paste the contents of combined changelog from Step 2.
+    tags](https://github.com/open-telemetry/opentelemetry-dotnet/tags) and find
+    the tag(s) which were pushed. Click the three dots next to the tag and
+    choose `Create release`.
+      * Give the release a name based on the tags created (e.g.
+      `core-1.9.0-beta.1` or `Instrumentation.Http-1.8.0`).
+      * Paste the contents of combined changelog from Step 2. Only include
+        projects with changes.
       * Check "This is a pre-release" if applicable.
       * Click "Publish release". This will kick off the [Pack and publish to
-      MyGet workflow](https://github.com/open-telemetry/opentelemetry-dotnet/actions/workflows/publish-packages-1.0.yml).
+      MyGet
+      workflow](https://github.com/open-telemetry/opentelemetry-dotnet/actions/workflows/publish-packages-1.0.yml).
 
  8. Validate using MyGet packages. Basic sanity checks :)
 
  9. From the above build, get the artifacts from the drop, which has all the
     NuGet packages.
 
-10. Copy all the NuGet files and symbols into a local folder. If only releasing
-    core packages, only copy them over.
+10. Copy all the NuGet files and symbols for the packages being released into a
+    local folder.
 
 11. Download latest [nuget.exe](https://www.nuget.org/downloads) into the same
-    folder from Step 9.
+    folder from Step 10.
 
-12. Obtain the API key from nuget.org (Only maintainers have access)
+12. 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.
 
-13. Run the following commands from PowerShell from local folder used in Step 9:
+13. Run the following commands from PowerShell from local folder used in Step 10:
 
     ```powershell
     .\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}
     ```
 
-14. Packages would be available in nuget.org in few minutes. Validate that the
-    package is uploaded.
+14. 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.
+
+15. If a new stable version of the core packages was released, open a PR to
+    update the `OTelLatestStableVer` property in `Directory.Packages.props` to
+    the just released stable version.
 
-15. Delete the API key generated in Step 11.
+16. If a new stable version of a package with a dedicated `MinVerTagPrefix` was
+    released (typically instrumentation packages) open a PR to update
+    `PackageValidationBaselineVersion` in the project file to reflect the stable
+    version which was just released.
 
-16. Update the OpenTelemetry.io document
-    [here](https://github.com/open-telemetry/opentelemetry.io/tree/main/content/en/docs/net)
-    by sending a Pull Request.
+17. If a new stable version of the core packages was released, open an issue in
+    the
+    [opentelemetry-dotnet-contrib](https://github.com/open-telemetry/opentelemetry-dotnet-contrib)
+    repo to notify maintainers to begin upgrading dependencies.
 
-17. If a new stable version of the core packages were released, update
-    `OTelLatestStableVer` in Directory.Packages.props to the just released
-    stable version.
+18. Once the packages are available on nuget.org post an announcement in the
+    [Slack channel](https://cloud-native.slack.com/archives/C01N3BC2W7Q). Note
+    any big or interesting new features as part of the announcement.
diff --git a/build/UnstableCoreLibraries.proj b/build/UnstableCoreLibraries.proj
@@ -0,0 +1,23 @@
+<Project>
+  <ItemGroup>
+    <SolutionProjects Include="..\**\OpenTelemetry.Exporter.Prometheus.AspNetCore*.csproj" />
+    <SolutionProjects Include="..\**\OpenTelemetry.Exporter.Prometheus.HttpListener*.csproj" />
+    <SolutionProjects Include="..\**\OpenTelemetry.Shims.OpenTracing*.csproj" />
+
+    <TestProjects Include="..\test\**\OpenTelemetry.Exporter.Prometheus.AspNetCore.Tests.csproj" />
+    <TestProjects Include="..\test\**\OpenTelemetry.Exporter.Prometheus.HttpListener.Tests.csproj" />
+    <TestProjects Include="..\test\**\OpenTelemetry.Shims.OpenTracing.Tests.csproj" />
+  </ItemGroup>
+
+  <Target Name="Build">
+    <MSBuild Projects="@(SolutionProjects)" Targets="Build" ContinueOnError="ErrorAndStop" />
+  </Target>
+
+  <Target Name="Restore">
+    <MSBuild Projects="@(SolutionProjects)" Targets="Restore" ContinueOnError="ErrorAndStop" />
+  </Target>
+
+  <Target Name="VSTest">
+    <MSBuild Projects="@(TestProjects)" Targets="VSTest" ContinueOnError="ErrorAndStop" />
+  </Target>
+</Project>
diff --git a/src/Directory.Build.targets b/src/Directory.Build.targets
@@ -1,8 +1,12 @@
 <Project>
 
   <PropertyGroup>
-    <!-- Note: PackageValidationBaselineVersion is defined in targets because $(MinVerTagPrefix) is not available to props as they apply before csproj. -->
+    <!-- Note: PackageValidationBaselineVersion and IsPackable are defined in
+    targets because $(MinVerTagPrefix) is not available in props files as they
+    apply before csproj. -->
     <PackageValidationBaselineVersion Condition="'$(MinVerTagPrefix)' == 'core-'">$(OTelLatestStableVer)</PackageValidationBaselineVersion>
+    <IsPackable Condition="'$(PackTag)' != '' AND $(PackTag.StartsWith($(MinVerTagPrefix))) == false">false</IsPackable>
+
     <TargetFrameworkMonikerAssemblyAttributesPath>$([System.IO.Path]::Combine('$(IntermediateOutputPath)','$(TargetFrameworkMoniker).AssemblyAttributes$(DefaultLanguageSourceExtension)'))</TargetFrameworkMonikerAssemblyAttributesPath>
   </PropertyGroup>
 

diff --git a/...emetry.Exporter.Prometheus.AspNetCore/OpenTelemetry.Exporter.Prometheus.AspNetCore.csproj b/...emetry.Exporter.Prometheus.AspNetCore/OpenTelemetry.Exporter.Prometheus.AspNetCore.csproj
@@ -5,18 +5,24 @@
     <TargetFrameworks>$(TargetFrameworksForPrometheusAspNetCore)</TargetFrameworks>
     <Description>ASP.NET Core middleware for hosting OpenTelemetry .NET Prometheus Exporter</Description>
     <PackageTags>$(PackageTags);prometheus;metrics</PackageTags>
-    <MinVerTagPrefix>core-</MinVerTagPrefix>
+    <MinVerTagPrefix>coreunstable-</MinVerTagPrefix>
     <DefineConstants>$(DefineConstants);PROMETHEUS_ASPNETCORE</DefineConstants>
 
     <!-- this is temporary. will remove in future PR. -->
     <Nullable>disable</Nullable>
   </PropertyGroup>
 
-  <!--Do not run Package Baseline Validation as this package has never released a stable version.
-  Remove this property once we have released a stable version.-->
-  <PropertyGroup>
-    <DisablePackageBaselineValidation>true</DisablePackageBaselineValidation>
-  </PropertyGroup>
+  <ItemGroup Condition="'$(RunningDotNetPack)' != 'true'">
+    <ProjectReference Include="$(RepoRoot)\src\OpenTelemetry\OpenTelemetry.csproj" />
+  </ItemGroup>
+
+  <ItemGroup Condition="'$(RunningDotNetPack)' == 'true'">
+    <PackageReference Include="OpenTelemetry" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <FrameworkReference Include="Microsoft.AspNetCore.App" />
+  </ItemGroup>
 
   <ItemGroup>
     <Compile Include="$(RepoRoot)\src\Shared\Guard.cs" Link="Includes\Guard.cs" />
@@ -32,13 +38,5 @@
     <Compile Include="$(RepoRoot)\src\Shared\ExceptionExtensions.cs" Link="Includes\ExceptionExtensions.cs" />
   </ItemGroup>
 
-  <ItemGroup>
-    <ProjectReference Include="$(RepoRoot)\src\OpenTelemetry\OpenTelemetry.csproj" />
-  </ItemGroup>
-
-  <ItemGroup>
-    <FrameworkReference Include="Microsoft.AspNetCore.App" />
-  </ItemGroup>
-
 </Project>