Skip to content

preview-branch-preparation.md

Latest commit

 

History

History
196 lines (142 loc) · 9 KB

preview-branch-preparation.md

File metadata and controls

196 lines (142 loc) · 9 KB

Preview Branch Preparation Process

This document outlines the process we go through during previews to prepare the branches for a workloads insertion.

Overview

When preparing for a new preview release of .NET, we need to ensure that the workload-versions repository is properly configured to receive and flow dependencies from the correct sources. This involves updating Maestro subscriptions to point to the appropriate channels for the preview period.

Process Steps

1. Change the Channel for the dotnet/dotnet Subscription

The workload-versions repository receives dependencies from the dotnet/dotnet repository (the VMR - Virtual Monolithic Repository) through Maestro subscriptions. During preview periods, we need to update these subscriptions to point to the correct preview channel.

Steps to Update the Subscription:

  1. Identify the target preview channel

    • Preview channels typically follow the pattern: .NET <version>.0.1xx SDK Preview <number>
    • Example: .NET 10.0.1xx SDK Preview 1, .NET 10.0.1xx SDK Preview 2, etc.
    • For RC1, RC2, and servicing releases, the channel form is: .NET <version>.0.1xx SDK Internal (for MSRC releases)
    • You can list available channels using: darc get-channels

  2. Find the current subscription

    • List all subscriptions for the repository: 
      darc get-subscriptions --target-repo workload-versions --source-repo dotnet/dotnet --target-branch main
    • Identify the subscription from dotnet/dotnet (the VMR)

    [!NOTE] For RC1, RC2, and servicing releases, the subscription source is from dotnet-dotnet (the internal Azure DevOps URI: https://dev.azure.com/dnceng/internal/_git/dotnet-dotnet).

  3. Update the subscription to the new preview channel

    • Use the DARC tool to update the subscription: 
      darc update-subscription --id <subscription-id> --channel "<channel-name>"
    • Example: 
      darc update-subscription --id 12345 --channel ".NET 10.0.1xx SDK Preview 2"

  4. Verify the subscription update

    • Confirm the change was applied: 
      darc get-subscription --id <subscription-id>
    • Check that the Channel field shows the new preview channel

  5. Monitor dependency flow

    • After updating the subscription, monitor for new pull requests from Maestro
    • PRs will be automatically created when new builds are published to the preview channel
    • These PRs will update the eng/Version.Details.xml file with new dependency versions

2. Update Branch Configuration

For major version previews shipped from the main branch:

  1. Work from the main branch

    • Major version previews (e.g., .NET 10 RC 1, RC 2) are typically shipped from the main branch
    • No separate preview branch is needed for these releases

  2. Update Version.props

    • Set the appropriate version features and patch levels for the preview
    • Update VersionFeature to match the SDK release band
    • Ensure VersionPatch is set correctly (typically 0 for a new preview)

  3. Configure channel publishing

    • Ensure builds from this branch publish to the correct workloads feed
    • For .NET 10: dotnet10-workloads feed
    • Feed URL: https://pkgs.dev.azure.com/dnceng/public/_packaging/dotnet10-workloads/nuget/v3/index.json

3. Update Package IDs for MAUI Packages

When transitioning to a new preview, you need to update the package ID suffixes for all MAUI-related packages in eng/Versions.props.

Steps to Update MAUI Package IDs:

  1. Locate the MauiWorkloads property group

    • Open eng/Versions.props
    • Find the <PropertyGroup Label="MauiWorkloads"> section

  2. Update the MauiFeatureBand property

    • Change to match the new preview version
    • Example: <MauiFeatureBand>10.0.100-rc.2</MauiFeatureBand>

  3. Update all MAUI manifest package property names

    • The property names encode the SDK band and preview in their suffix
    • For example, when moving from RC 1 to RC 2:
      • MicrosoftNETSdkAndroidManifest100100rc1PackageVersion → MicrosoftNETSdkAndroidManifest100100rc2PackageVersion
      • MicrosoftNETSdkiOSManifest100100rc1PackageVersion → MicrosoftNETSdkiOSManifest100100rc2PackageVersion
      • MicrosoftNETSdktvOSManifest100100rc1PackageVersion → MicrosoftNETSdktvOSManifest100100rc2PackageVersion
      • MicrosoftNETSdkMacCatalystManifest100100rc1PackageVersion → MicrosoftNETSdkMacCatalystManifest100100rc2PackageVersion
      • MicrosoftNETSdkmacOSManifest100100rc1PackageVersion → MicrosoftNETSdkmacOSManifest100100rc2PackageVersion
      • MicrosoftNETSdkMauiManifest100100rc1PackageVersion → MicrosoftNETSdkMauiManifest100100rc2PackageVersion

  4. Update the references to these properties

    • Update property references in the assignment statements: 
      <MauiWorkloadManifestVersion>$(MicrosoftNETSdkMauiManifest100100rc2PackageVersion)</MauiWorkloadManifestVersion>
<XamarinAndroidWorkloadManifestVersion>$(MicrosoftNETSdkAndroidManifest100100rc2PackageVersion)</XamarinAndroidWorkloadManifestVersion>
<!-- And so on for all workloads -->

  5. Verify all package property names are updated consistently

    • Ensure the suffix pattern matches across all MAUI workload packages
    • The pattern should be: {Major}{Minor}{Band}{PreviewLabel}{PreviewNumber}
    • Example: 100100rc2 represents 10.0.100-rc.2

4. Update VS Manifest IDs for Mono and Emsdk Workloads

Visual Studio integration requires updating the VSMAN (Visual Studio Manifest) IDs and external.vsmanproj references for mono and emsdk workloads when preparing for a new preview.

Steps to Update VS Manifest Configuration:

  1. Update VSMAN IDs in dotnet-workloads-components.json

    • The VSMAN IDs need to be updated to match the new preview version
    • These IDs are referenced in dotnet-workloads-components.json
    • Update the VSMAN references for mono and emsdk workloads in this configuration file

  2. Update VisualStudio.External.vsmanproj for mono workload

    • Locate the VisualStudio.External.vsmanproj file for the mono workload
    • Update any version-specific identifiers to match the new preview
    • Ensure the ComponentId reflects the correct preview version

  3. Update VisualStudio.External.vsmanproj for emsdk workload

    • Similarly, update the VisualStudio.External.vsmanproj file for the emsdk (Emscripten) workload
    • Update version identifiers and component references
    • Verify the ComponentId aligns with the new preview numbering

  4. Coordinate with VS insertion process

    • The VS insertion pipeline may need configuration updates for the new preview
    • Ensure the VSMAN package generation is set up for the correct preview channel
    • Test the insertion process with a test build before the official preview release

Note

The exact location and format of VSMAN configuration files may vary based on the repository structure and VS insertion setup.

Reference Information

Workloads Feeds by .NET Version

Useful DARC Commands

# List all channels
darc get-channels

# List subscriptions for this repository
darc get-subscriptions --target-repo workload-versions

# Get details of a specific subscription
darc get-subscription --id <subscription-id>

# Update a subscription's channel
darc update-subscription --id <subscription-id> --channel "<channel-name>"

# List available builds in a channel
darc get-builds --channel "<channel-name>"

Documentation Links

Common Issues and Troubleshooting

Subscription Not Updating

If dependency PRs are not being created after updating the subscription:

  1. Verify the subscription channel is correct
  2. Check that builds are being published to the target channel
  3. Ensure the subscription is enabled (not disabled)
  4. Check Maestro for any errors in the subscription processing

Wrong Dependencies Flowing In

If you're receiving dependencies from the wrong builds:

  1. Verify the subscription is pointing to the correct channel
  2. Check the channel's build sources
  3. Ensure you updated the correct subscription (there may be multiple)

Timeline Considerations

  • Subscription channel updates should be made before the first preview build is published
  • Allow time for the first dependency update PR to flow through and be merged
  • Coordinate with the dotnet/dotnet (VMR) team on preview build schedules
  • Plan for at least one full dependency flow cycle before declaring the branch ready for insertions