diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 53825b7d256..de2e70a97c1 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -1,9 +1,15 @@ +**History Notes:** +(Fill in the following template if multiple notes are needed, otherwise PR title will be used for history note.) + +[Component Name 1] (BREAKING CHANGE:) (az command:) make some customer-facing change. +[Component Name 2] (BREAKING CHANGE:) (az command:) make some customer-facing change. + --- This checklist is used to make sure that common guidelines for a pull request are followed. -- [ ] The PR has modified HISTORY.rst describing any customer-facing, functional changes. Note that this does not include changes only to help content. (see [Modifying change log](https://github.com/Azure/azure-cli/tree/master/doc/authoring_command_modules#modify-change-log)). +- [ ] The PR title and description has followed the guideline in [Submitting Pull Requests](https://github.com/Azure/azure-cli/tree/dev/doc/authoring_command_modules#submitting-pull-requests). - [ ] I adhere to the [Command Guidelines](https://github.com/Azure/azure-cli/blob/dev/doc/command_guidelines.md). diff --git a/doc/authoring_command_modules/README.md b/doc/authoring_command_modules/README.md index 99b5f8bf853..e1819caf145 100644 --- a/doc/authoring_command_modules/README.md +++ b/doc/authoring_command_modules/README.md @@ -199,28 +199,39 @@ azdev style --module [--pylint] [--pep8] Submitting Pull Requests ------------------------ -### Modify Change Log +### Format PR Title -Modify the `HISTORY.rst` for any customer-facing changes. If a module has changed at all since a previous release so that a version bump is required, it is fine to add a generic entry that says "* Minor fixes.". +History notes are auto-generated based on commit messages and descriptions starting from [S165](https://github.com/Azure/azure-cli/milestone/82). The commmit message for the squashed merge commit defaults to the PR title. Starting from 01/30/2020, we require all the PR titles to follow the below format: +1. [**Mandatory**] Each commit message must start with `[Component Name]` or `{Component Name}`. + * `Component Name` shall be replaced by the real ones such as `Storage`, `Compute`. It could be the name of a command module, but in title case with necessary spaces for better readability, such as `API Management`, `Managed Service`. Other possible component names include but are not limited to: `Packaging`, `Misc.`, `Aladdin`. + * `[]` means this change is customer-facing and the message will be put into `HISTORY.rst`. `{}` means this change is not customer-facing and the message will **NOT** be included in `HISTORY.rst`. + * If the component name is `Core`, the message will be written in `src/azure-cli-core/HISTORY.rst`. Otherwise, the message will be written in `src/azure-cli/HISTORY.rst`. +2. [**Mandatory**] If it's a breaking change, the second part should be `BREAKING CHANGE` followed by a colon. In the case of hotfix, put `Hotfix` in this part. For other cases, this part should be empty. +3. [**Recommendation**] If the change can be mapped into a command, then the next part could be the command name, followed by a colon. +4. [**Recommendation**] Use the right verb with present-tense in original form to descibe what is done: + * **Add** for new features. + * **Change** for changes in existing functionality. + * **Deprecate** for once-stable features removed in upcoming releases. + * **Remove** for deprecated features removed in this release. + * **Fix** for any bug fixes. -This will be the release notes for the next release. +An example title of customer-facing change PR: -e.g.: -``` -.. :changelog: +>[Storage] BREAKING CHANGE: az storage remove: remove --auth-mode argument -Release History -=============== +An example title of non-customer-facing change PR: -0.0.3 -+++++ -* This is my customer-facing change. +>{Aladdin} Add help example for dns -0.0.2 -+++++ -* Minor fixes. +### Format PR Description -0.0.1 -+++++ -* Initial release -``` +If you would like to write multiple history notes for one PR, please write the notes under `History Notes` section in the PR description, following the same format described above. In this case, the PR title should be a summary of all the changes in this PR and will not be put into `HISTORY.rst`. + +Other than that, you can put any reasonable information in the description above the `History Notes` part. + +### Only Modify HISTORY.rst for Hotfix +As described above, history notes will be auto-generated and inserted into `HISTORY.rst` during release. When submitting a normal PR, you don't need to modify `HISTORY.rst` manually. In the case of hotfix, you should create a hotfix branch based on release branch and submit a PR to merge hotfix into release. In this PR, if you have customer-facing changes, you need to modify `HISTORY.rst` to add history notes. Later on you also need to merge the hotfix branch into dev branch and the second part of the PR title should be `Hotfix`. The auto-generation of history notes for the next release will ignore the commit that contains `Hotfix`. + +An example title of hotfix change PR: + +>{Packaging} Hotfix: fix dependency error