Feature request by Allegra Domel: automation for merging all changes to public specs repo main

[konrad-jamrozik]

From the Teams thread here:

[Allegra Domel] Is there an automated way to merge all of my code from RPSaaSMaster in the private repo, to the main branch in the public repo? (We are releasing our API for public preview soon). I know that I can have an individual PR merged into the main branch, but this only contains the most recent files I've changed (in that PR), and won't add all the other files (readmes, etc). Do I need to manually make a PR with all of the necessary files instead?

[Ray Chen] Unfortunately, currently there's no tool to support on this to take the whole api version to publish to public spec repo.

Example scenario

To elaborate, consider following scenario, from 4/12/2023, email thread withsubject Breaking Change Approval for AzureStackHCI. Here is what the user did step-by-step, and what is the problem:

Step 1: merge the new API version (AzureStackHCI 2023-03-01) to appropriate branch (RPSaaSMaster) in private specs repo

Folks have pushed to the private specs repo, a new API version of “ARM Microsoft.AzureStackHCI/stable/2023-03-01”.

This means they added this dir:
specification/azurestackhci/resource-manager/Microsoft.AzureStackHCI/stable/2023-03-01/*
Plus made an update to README:
specification/azurestackhci/resource-manager/readme.md

This was done in this PR: 11574

Because of the conventions, these changes were pushed to the RPSaaSMaster branch (main branch for private repo is mirrored from the public repo, so nothing can be pushed to it explicitly).

Step 2: publish the new API version to the public specs repo (problem: incomplete changes)

This was done in this PR (I deduced it from version history): 23255

The goal here was to have changes in this PR be equivalent to the changes from the PR in step 1.

So the same changes here:
specification/azurestackhci/resource-manager/Microsoft.AzureStackHCI/stable/2023-03-01/*
and to the README.

This time we are merging to main, as there main is the one official release branch for all public APIs.

But there was a problem: the PR 23255 actually did not have all the same changes as PR 11574.

Step 3: attempt to add the missing API version file changes without introducing new API version.

Now there is new PR to the public repo, 23495 which aims to patch up the gap: it includes the file changes that have been in PR 11574 but not 23255

This feature request

The idea here is that the problem arose because that in step 2 the user had to submit PR 23255 with appropriate changes manually, and ensure the changes are the same as in PR 11574 from step 1. This is error-prone process leading to issues, as demonstrated by the case described above.
Hence the feature request here is to facilitate smart/automated transplantation of new API version from the private repo to the public repo.

To solve it, there is some complexity here: what if the new API version in private repo was added across multiple PRs, not one? Should we bundle all the changes from all these PRs into one PR to public repo? What if these PRs have also other changes, unrelated to the new API version? If we don’t look at the PR, but instead only on the dir contents (just take the new API version dir as a whole), then we need to be careful about also including appropriate changes from the README, which is outside of the API dir (specification/azurestackhci/resource-manager/readme.md).

Note that in lieu of this solution, in ShiftLeft we are currently providing guidance like this:

• https://github.com/Azure/azure-rest-api-specs-pr/pull/12059#issuecomment-1506333911

[weshaggard]

@konrad-jamrozik I think it would be good to also copy the context into this issue as well as the teams link.

[konrad-jamrozik]

Note to self: include in the issue description the info I will get from the email thread FW: Breaking Change Approval for AzureStackHCI on 4/12/2023.