{Core} Add support and document for Breaking Change Pre-announce #28832
Conversation
️✔️AzureCLI-FullTest
|
azure-client-tools-bot-prd
bot
added this to the May 2024 (2024-05-21)❗ Breaking change release ❗ milestone
️✔️AzureCLI-BreakingChangeTest
|
|
breaking change pre-announce |
microsoft-github-policy-service
bot
added
Auto-Assign
| def _next_breaking_change_version(): | ||
| global __bc_version | ||
| if __bc_version: | ||
| return __bc_version | ||
| cur_version = packaging.version.parse(__version__) | ||
| next_bc_version = packaging.version.parse(NEXT_BREAKING_CHANGE_RELEASE) | ||
| if cur_version >= next_bc_version: | ||
| fetched_bc_version = _next_breaking_change_version_from_milestone(cur_version) | ||
| if fetched_bc_version: | ||
| __bc_version = fetched_bc_version | ||
| return fetched_bc_version | ||
| __bc_version = NEXT_BREAKING_CHANGE_RELEASE | ||
| return NEXT_BREAKING_CHANGE_RELEASE |
There was a problem hiding this comment.
When we release a CLI version with NEXT_BREAKING_CHANGE_RELEASE forget to change, when the cli users will see a different version every half year. My recommendation is that change the NEXT_BREAKING_CHANGE_RELEASE version number in the CLI release pipeline. Every time we bump up the cli version, the pipeline will check and change the NEXT_BREAKING_CHANGE_RELEASE version.
There was a problem hiding this comment.
I agree with that. If we could update the NEXT_BREAKING_CHANGE_RELEASE after breaking change release in pipeline, we don't need a fallback logic to get the version number.
| ### Pre-announce Breaking Changes | ||
|
|
||
| All breaking changes **must** be pre-announced several sprints ahead Release. There are two approaches to inform both interactive users and automatic users about the breaking changes. | ||
|
|
||
| 1. (**Mandatory**) Breaking Changes must be pre-announced through Warning Log while executing. | ||
| 2. (*Automatic*) Breaking Changes would be collected automatically and listed in [Upcoming Breaking Change](https://learn.microsoft.com/en-us/cli/azure/upcoming-breaking-changes). | ||
|
|
||
| ## Workflow | ||
|
|
||
| ### Overview | ||
|
|
||
| * CLI Owned Module | ||
| * Service Team should create an Issue that requests CLI Team to create the pre-announcement several sprints ahead Breaking Change Window. The CLI team will look at the issue and evaluate if it will be accepted in the next breaking change release. | ||
| * Please ensure sufficient time for CLI Team to finish the pre-announcement. | ||
| * The pre-announcement should be released ahead of Breaking Change Window. | ||
| * Service Owned Module | ||
| * Service Team should create a Pull Request that create the pre-announcement several sprints ahead Breaking Change Window. | ||
| * The pre-announcement should be released ahead of Breaking Change Window. | ||
| * After releasing the pre-announcement, a pipeline would be triggered, and the Upcoming Breaking Change Documentation would be updated. | ||
| * At the start of Breaking Change window, emails would be sent to notify Service Teams to adopt Breaking Changes. | ||
| * Breaking Changes should be adopted within Breaking Change Window. |
There was a problem hiding this comment.
Regarding the pre-announce breaking change process part, I personally suggest that PM @dcaro and @Jacekey23 can also help review it when they have time after the PR is ready
| ### Overview | ||
|
|
||
| * CLI Owned Module | ||
| * Service Team should create an Issue that requests CLI Team to create the pre-announcement several sprints ahead Breaking Change Window. The CLI team will look at the issue and evaluate if it will be accepted in the next breaking change release. |
There was a problem hiding this comment.
Perhaps we can consider asking service team to add the tag of breaking-change request to this type of issue, which can make it easier for us to pay attention to these important issues in the vast number of issues, it also facilitates us to conduct statistics and analysis through tag filtering in the future
There was a problem hiding this comment.
create an Issue
Additionally, it is recommended to provide a link of the corresponding feature request template here
There was a problem hiding this comment.
Perhaps we can consider asking service team to add the tag of
breaking-change requestto this type of issue
In the current Implementing Breaking Changes Doc, the created issue should be attached with Breaking Change label. I think we could follow that design.
There was a problem hiding this comment.
like the tag of breaking-change, it's worth having it and align with services to start using.
There was a problem hiding this comment.
Add a sentence
The issue should include the label Breaking Change.
|
|
||
| * CLI Owned Module | ||
| * Service Team should create an Issue that requests CLI Team to create the pre-announcement several sprints ahead Breaking Change Window. The CLI team will look at the issue and evaluate if it will be accepted in the next breaking change release. | ||
| * Please ensure sufficient time for CLI Team to finish the pre-announcement. |
There was a problem hiding this comment.
sufficient time
It would be better if more specific time suggestions could be provided
There was a problem hiding this comment.
maybe vote for sufficient time here?
4-week
6-week
10-week
There was a problem hiding this comment.
We can handle the pre-announce request in the same manner as other feature requests with a specific target date. For Breaking Change Pre-announce requests, the target date will be the release before the Breaking Change release.
|
|
||
| ### Breaking Change Window | ||
|
|
||
| The breaking change window *allows* for service command breaking changes. When a Pull Request is merged during this sprint, it will be included in the next Breaking Change Release. |
There was a problem hiding this comment.
would be "this sprint" refer to any sprint that comes right before Build/Ignite? It's nice if be clear about it.
There was a problem hiding this comment.
Changed the sentence to
The breaking change window is a designated sprint that permits the merging of service command breaking changes. Any Pull Request merged during this sprint will be included in the subsequent Breaking Change Release.
|
|
||
| The timing of the breaking change window in Azure CLI aligns with [Microsoft Build](https://build.microsoft.com/) and [Microsoft Ignite](https://ignite.microsoft.com/). You could find the next Breaking Change Release plan in our [milestones](https://github.com/Azure/azure-cli/milestones). | ||
|
|
||
| > If you would like to release ad-hoc breaking changes, reach out to the CLI team to provide an explanation for the necessity of these changes. The exceptions can be provide in the following cases: |
There was a problem hiding this comment.
my 2 cents here:
I personally like to rephrase this part and tie with why/what we build breaking change window, mentioned in the top.
Making the request easy will likely get us difficult to hold the door.
It's highlighted that we usually do not allow breaking changes check-ins within non-breaking-change window, based on what we stated above for consistency and stable tooling experience.
something unexpected can happen. We understand and would like to help out. There would be high-graded justifications required to provide the info Azure CLI can access.
p.s.
Noting that providing the required info for assessment does not mean it will be assured to be greenlighted for breaking changes. Team will still make the decision based on the overall impact.
There was a problem hiding this comment.
I agree with that. I have replaced the parts about the ad-hoc introduction of breaking changes. Kindly review the modified content and provide your feedback.
| ### Overview | ||
|
|
||
| * CLI Owned Module | ||
| * Service Team should create an Issue that requests CLI Team to create the pre-announcement several sprints ahead Breaking Change Window. The CLI team will look at the issue and evaluate if it will be accepted in the next breaking change release. |
There was a problem hiding this comment.
like the tag of breaking-change, it's worth having it and align with services to start using.
|
|
||
| * CLI Owned Module | ||
| * Service Team should create an Issue that requests CLI Team to create the pre-announcement several sprints ahead Breaking Change Window. The CLI team will look at the issue and evaluate if it will be accepted in the next breaking change release. | ||
| * Please ensure sufficient time for CLI Team to finish the pre-announcement. |
There was a problem hiding this comment.
maybe vote for sufficient time here?
4-week
6-week
10-week
|
/azp run |
|
Azure Pipelines successfully started running 3 pipeline(s). |
Hi @kairu-ms , Unit tests added in |
Co-authored-by: Xing Zhou <[email protected]>
|
minor: "implictly deprecated as a descendance because"..... |
|
/azp run |
|
Azure Pipelines successfully started running 3 pipeline(s). |
Co-authored-by: Xing Zhou <[email protected]>
|
|
||
| ```python | ||
| # src/azure-cli/azure/cli/command_modules/vm/custom.py | ||
| from azure.cli.core.breaking_change import register_conditional_breaking_change, AzCLIOtherChange |
There was a problem hiding this comment.
AzCLIOtherChange is imported but unused.
| **Note:** We strongly recommend using this method to display breaking change warnings under specific conditions instead of using `logger.warning` directly. This approach enables centralized documentation of breaking changes and assists in automating customer notifications. | ||
|
|
||
| ```python | ||
| # src/azure-cli/azure/cli/command_modules/vm/custom.py |
There was a problem hiding this comment.
Should this file be _breaking_change.py? custom.py won't be loaded when loading the command module.
There was a problem hiding this comment.
Fix conditional breaking change regarding issues in another PR #31060
|
|
||
| # src/azure-cli/azure/cli/command_modules/vm/custom.py | ||
| def create_vm(cmd, vm_name, **): | ||
| from azure.cli.core.breaking_change import print_conditional_breaking_change |
There was a problem hiding this comment.
We usually use 4 spaces for indentation.
|
|
||
| # src/azure-cli/azure/cli/command_modules/vm/custom.py | ||
| def create_vm(cmd, vm_name, **): | ||
| from azure.cli.core.breaking_change import print_conditional_breaking_change |
There was a problem hiding this comment.
This import statement should be inside if some_condition.
Related command
Description
Introduce an additional method to pre-announce upcoming breaking changes as well as deprecation. This will help with the collection of announced breaking changes.
Pre-announce Command Group Deprecate
Pre-announce Command Deprecate
Pre-announce Argument Deprecate
Pre-announce Argument Renaming
Pre-announce Argument Being Required
Pre-announce Default Value Change
Pre-announce Output Change
Pre-announce Logic Change
Pre-announce multiple breaking changes in one command and its parent group
Pre-announce multiple breaking changes in single argument
Announce Custom Breaking Change
Testing Guide
History Notes
[Component Name 1] BREAKING CHANGE:
az command a: Make some customer-facing breaking change[Component Name 2]
az command b: Add some customer-facing featureThis checklist is used to make sure that common guidelines for a pull request are followed.
The PR title and description has followed the guideline in Submitting Pull Requests.
I adhere to the Command Guidelines.
I adhere to the Error Handling Guidelines.