Ship dotnet-maintenance-packages

[ericstj]

• [x] Enable internal build - may require assigning service tree entry - get help from @rbhanda
• [x] Define branch scheme for releases, create internal branch
• [x] Update the SDK / tools / arcade - 8.0
• [x] Adopt NuGet Central Package Management
• [x] Remove non-needed infrastructure
  • [x] test infra already provided by Arcade
  • [x] Publishing.props.
• [x] Remove the Build.proj as we already have a solution file
• [x] Clean-up the feeds, we shouldn't point to any previous release.
• [x] Enable APICompat + baseline validation
• [x] Enable package validation?
• [x] Do a trial run of an existing package
  • [x] Move source & test code over with history
  • [x] Retarget to in-support frameworks - make sure to define properties like NETFrameworkMinimum etc.
  • [x] Ensure we add targets to package that message out of support frameworks: https://github.com/dotnet/runtime/blob/5cb5dafd4d49f171425958e4d92d9e9066cad58b/eng/packaging.targets#L201
  • [x] Is there any other infrastructure from dotnet/runtime libraries build that we need to move over? @ViktorHofer
  • [x] Enable APICompat for package (turning on and setting baseline package version, restoring it).
  • [x] Enable package for servicing by setting properties to version & build it.
  • [ ] Document along the way :)
• [ ] Refine Assembly versioning pattern, document the process, and trial it (readiness)
• [x] Determine which version of Arcade is appropriate for this repo -- which will need to regularly ship from main -> We decided to stick with Arcade 9 for now with the option to downgrade to the LTS version (8.0) if necessary.
• [x] Version and update System.Buffers to be ready to ship. (drop out of support frameworks)
• [x] Capture the list of packages which need to be moved here and set a timeline for each. https://github.com/dotnet/maintenance-packages/issues/42
• [x] Prepare public docs describing support lifecycle for these packages. https://github.com/dotnet/core/pull/9206 and https://github.com/dotnet/maintenance-packages/issues/42
• [x] Enable analyzer that suggests the correct license header.
• [ ] Determine how new builds of packages that ship from this repo flow into the rest of the product - eg: Microsoft.Windows.Compatibility, netstandard2.0 and netframework builds from in-support branches.
• [ ] Decide and document what's our cadence of proactive servicing to drop out of support frameworks from packages in maintenance-packages.
  • No proactive servicing
  • Proactive servicing each time an LTS framework goes out of support.
• [x] Decide and document how to deprecate old versions of packages that get replaced by maintenance-packages.
• [ ] In August 2024, create a breaking change doc, publish new versions for all of them. The old packages will get automatically marked as deprecated. But Unsafe should be the exception, we don't deprecate that one at the same time as the others. Unsafe will get marked as out of support when 6.0 goes out of support.
• [ ] Ensure the ASP.NET doc PR gets merged https://github.com/dotnet/website/pull/6257
• [ ] Write package readmes for all the ported libraries and consider adding build validation: https://github.com/dotnet/maintenance-packages/pull/43

cc @ViktorHofer @carlossanlop

[carlossanlop]

Update the SDK / tools / arcade - 8.0

I assume we want to update to 8.0 because this repo is merely for servicing, so we want the latest released version of arcade, not the one currently in development. Correct?

In that case, I updated this repo's darc subscription to arcade to point to the .NET 8 Eng channel (it was pointing to 7).

Here's the deps flow PR, it was already open, but triggering the subscription updated the same PR: https://github.com/dotnet/maintenance-packages/pull/17

[ericstj]

I assume we want to update to 8.0 because this repo is merely for servicing

That was my assumption as well. I was also expecting us to want to ship from this repo before 9.0 releases.

@ViktorHofer can you let us know what features we might need out of 9.0 here? Could those be backported to 8.0 arcade to avoid a dependency on non-stable tools?

[ViktorHofer]

@ViktorHofer can you let us know what features we might need out of 9.0 here? Could those be backported to 8.0 arcade to avoid a dependency on non-stable tools?

None. 8.0 and 9.0 versions of the Arcade.Sdk are nearly identical aside from version updates.

[ViktorHofer]

Refine Assembly versioning pattern

@ericstj I'm unsure what this item tracks, can you please elaborate? @carlossanlop and I met few weeks ago, discussed the versioning infrastructure and agreed on that what we now have in main makes sense and just needs documentation.

[ericstj]

One thing I noticed is that it needs to handle cases with pinned assembly versions and non-pinned in the same package. For example for packages like System.Buffers and System.Memory we'd need to freeze the netstandard & netcore assembly versions while rev'ing the netframework one. I think it needs more discussion to understand all the details of how it works. Ideally I want to make sure we keep it simple without developers having to maintain complexity in their projects. It's possible that the current scheme can achieve this, but we need to work that out. I said "refine" here to indicate that what we have is fine we just need to walk through all the cases it needs to handle (package types and servicing operations) and describe how those work and make any changes we see necessary.

My assumptions based on what I'm seeing right now (this is not complete, but this is the sort of docs I'm expecting that might reveal what refinement we need).

Initial porting:

1. PackageVersion should initially be one minor version higher than the last shipped package version.
2. AssemblyVersion should be initially set as follows:
   • Same as last shipped for any library compatible with a shared-framework library
   • Incremented from last shipped otherwise (EG: NetFramework target, or non-shared-framework library).
   • NOTE: there may be special cases like https://github.com/dotnet/runtime/blob/465e0060782c84bfc086971e507e5c5dabd7c12f/src/libraries/System.Speech/Directory.Build.targets#L4-L6 where AssemblyVersion should remain fixed.
3. PackageValidationBaselineVersion should be set to the last shipped package version.

Every release time:

1. Developers set IsPackable on a project when they wish for that project to ship in a given release.
2. A branding operation done by the repo owner is responsible for incrementing AssemblyVersion, PackageVersion, PackageValidationBaselineVersion after a release when a package set's IsPackable.
   • NOTE: any frozen AssemblyVersions should not be incremented, we should distinguish these in some way.

[ViktorHofer]

Yes that exactly describes what we currently do in main. I just had another meeting with @carlossanlop and he will document the steps.

Our plan is to do the first few version updates ourselves and then automate that process via the Azure SDK bot.

[ericstj]

Something I couldn't quite see working here is how the AssemblyVersion exclusions will work - how do we keep those separate and make sure the branding operations won't touch them?

[ViktorHofer]

I would just move the fixed assembly version somewhere else so that whoever increments the versions (i.e. a bot) doesn't touch it. And I recommend to add a code comment to highlight that the assembly version is frozen because of X.

Alternatively we could keep the line where it is and just add an inline (in the same line) xml comment to make the bot ignore the line but at the same time explain that this is frozen, i.e.

<AssemblyVersion>4.0.3.0</AssemblyVersion> <!-- NO-INCREMENT: This version is frozen for .NET Standard and .NETCoreApp because the assembly ships inbox. -->

The Azure SDK bot might already have such a capability but if not, adding that should be easy: !line.Contains("NO-INCREMENT").

[carlossanlop]

Refine Assembly versioning pattern, document the process, and trial it (readiness)

@ericstj is it possible to try the servicing process without accidentally pushing the nuget package?

[ViktorHofer]

Yeah you can change the default channel to General Testing so that a package gets pushed to the general testing nuget feed only.

[ericstj]

We should also make sure that these stable builds don't directly publish to shared feeds. Normally our stable servicing builds of repos like dotnet/runtime will push their stable packages to a temporary feed. (perhaps separately) We should make sure this repo is set up to do that.

Additionally we might think about if it makes sense to have this repo produce "pre-release" servicing packages so that it's easier to test nightly builds. Then we flip the switch at some point to make it stable.

[carlossanlop]

Define branch scheme for releases, create internal branch

Done. I created a branch named internal/main and made sure it got registered in dotnet/versions so it gets all changes introduced to main mirrored into it (internal-code-merge pipeline).

The internal main branch already existed and it was already working well with the regular code-mirror pipeline.

[ViktorHofer]

Determine how new builds of packages that ship from this repo flow into the rest of the product - eg: Microsoft.Windows.Compatibility, netstandard2.0 and netframework builds from in-support branches.

Just my take on this, I don't think repositories should connect to maintenance-packages via dependency flow. I would rather have them use dependabot to update packages when a new version's out on nuget.org.

[ericstj]

Determine how new builds of packages that ship from this repo flow into the rest of the product - eg: Microsoft.Windows.Compatibility, netstandard2.0 and netframework builds from in-support branches.

Just my take on this, I don't think repositories should connect to maintenance-packages via dependency flow. I would rather have them use dependabot to update packages when a new version's out on nuget.org.

NuGet.org might be too late in the case of servicing events that we wish to sim-ship - suppose a critical fix to System.Memory that needs be referenced by many products. Still I don't think dependency flow is the answer because that's used for product releases.