Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

{Document} Modify PR template and document #11913

Merged
merged 4 commits into from
Jan 30, 2020
Merged

{Document} Modify PR template and document #11913

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
7d5bf57
modify PR template and doc
fengzhou-msft Jan 21, 2020
f5e7f17
format
fengzhou-msft Jan 21, 2020
a2afbf7
update PR readme
fengzhou-msft Jan 22, 2020
d3c9cee
fix typo
fengzhou-msft Jan 30, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 7 additions & 1 deletion .github/pull_request_template.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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).
47 changes: 29 additions & 18 deletions doc/authoring_command_modules/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -199,28 +199,39 @@ azdev style --module <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:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

not related to this PR, what's our plan for PR created before 1/30/2020, but not merged when 1/30? we'll update all the title?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For thoses PRs, if they modified HISTORY.rst, they would have conflicts with latest dev branch. We can just remove the notes in HISTORY.rst and change PR title or description accordingly.

If the PR does not modify HISTORY.rst, we should change those start with [] to {}. We can leave the rest that do not follow our new format untouched since they will be ignored when generating history notes.

We can publicize such action during the release meeting on 1/30/2020.

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`.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do we have a list of valid component names?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Based on statistics of all past history notes, most component names can be mapped to command module name, the format could vary though. So we just want to use the same format for component name.

I don't think we want to limit the name to a list as we will have new modules and also other aspects like changes for CI, Packaging and more. We may come up with component name recommendations for changes not related to command modules when we have more data later.

* `[]` 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