Treat autogenerated content as build artifacts owned by CI/CD, and handle breaking changes through the release system (not ad-hoc edits).
Do:
- Edit the source-of-truth inputs (e.g., custom folder content and autorest README.md/autorest configuration) and place human-authored examples under the dedicated “examples” directory.
- Run the module build script (e.g., build-module.ps1) to regenerate docs/help/examples/test stubs.
- For large “generated/” mirrors, rely on the automated post-merge Archive pipeline to regenerate and commit; feature PRs should not duplicate that automation.
- For breaking changes, use the CI/CD/release conventions: add/maintain the breaking-change announcement directive with the correct versioning, and follow the team’s breaking-change release tracking rules.
Don’t:
- Manually edit files under paths described as auto-generated (docs/help/examples/test stubs/generated mirrors). Those edits will be overwritten.
- Commit regenerated “generated/…” outputs from feature branches.
Example (Autorest breaking-change announcement):
directive:
#breaking change announcement
- where:
verb: Update
subject: NetworkCloudVirtualMachine
set:
breaking-change:
change-description: The Update-AzNetworkCloudVirtualMachine cmdlet no longer supports the JsonString and JsonFilePath parameters.
deprecated-by-version: 2.0.3
Apply this standard whenever you’re touching module docs/help/tests or any release-related breaking-change metadata—ensure your PR changes inputs, not outputs, and that breaking-change signaling matches the pipeline’s release/version expectations.