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

Update change log common headings #3103

Merged
merged 3 commits into from
Jul 1, 2021
Merged

Update change log common headings #3103

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
8aae181
Update change log common headings
weshaggard Jun 30, 2021
26e40bb
Update releasenotes.md
weshaggard Jun 30, 2021
cf8cbd3
Apply suggestions from code review
weshaggard Jul 1, 2021
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
10 changes: 5 additions & 5 deletions docs/policies/releasenotes.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,13 +36,13 @@ The release notes consist of four sections:

We don't want to advertise every single bug fix as most of them do not impact the way customers think about developing the client. The [change log](https://azure.github.io/azure-sdk/policies_releases.html#change-logs) provides an exhaustive list of changes. We don't need to duplicate it.

However, in the release notes we do want to list critical changes for customers. A critical change is one that the developer would either need to know or want to know. Use the following section headers (`Features Added`, `Breaking Changes`, and `Key Bugs Fixed`) for the defined critical changes:
However, in the release notes we do want to list critical changes for customers. A critical change is one that the developer would either need to know or want to know. Use the following section headers (`Features Added`, `Breaking Changes`, and `Bugs Fixed`) for the defined critical changes:
weshaggard marked this conversation as resolved.
Show resolved Hide resolved

* *Features Added* - For new features to be called out in release notes
* *Breaking Changes* - For changes to be called out in release notes including, changes that break existing functionality, soon-to-be removed features, now removed features
* *Key Bugs Fixed* - For important bug fixes to be called out in release notes, including any security fixes
* *Features Added* - For new features to be called out in release notes.
Copy link
Member

Choose a reason for hiding this comment

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

I assume this would need to be addressed separately, but it would be great if we can get this ghost text to populate in the Changelogs so we don't have to look up the guidelines every time we want to double check on something.

Copy link
Member Author

Choose a reason for hiding this comment

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

I was trying to figure out how to provide some ghost text or links to changelog guidelines in the MD files but I don't know a good way to do it without breaking validation or without it accidently shipping in the changelog content. If you have some ideas on how to make that happen I'm open to them.

Copy link
Member

Choose a reason for hiding this comment

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

Don't we have validation right now that checks for empty sections? Could we also add a check for the ghost text, or are we worried that it might change and then no longer work?

Copy link
Member Author

Choose a reason for hiding this comment

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

Exactly checking for exact text is dangerous because even a slight change would leave it behind. It would be a little safer to add our link in there and then validation can ensure that link doesn't exist in the content.

Copy link
Member

Choose a reason for hiding this comment

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

That makes sense - seeing as the sections will need to be updated anyway before release, I think having the link in there that would need to be deleted wouldn't be too much of an added burden.

Copy link
Member Author

Choose a reason for hiding this comment

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

Lets consider that as a follow-up improvement once people start getting used to the template being in there maybe it won't be needed.

* *Breaking Changes* - For any changes that the will break the customer in some way, such as breaking existing functionality, soon-to-be removed features, or now removed features.
* *Bugs Fixed* - For important bug fixes to be called out in release notes, including any security fixes. Include things that the customer would likely notice or need to react to in some way.

For example, "fixed a bug in which the event processor would stop working if you received no events for 30 minutes" does not qualify. While you may list this under the `Fixed` heading in the changelog, the customer does not need to do anything, and it's fairly likely they have not bumped into this error, so this shouldn't be listed under the `Key Bugs Fixed` heading. However, "Added a new overload to the constructor to support AzureAD credentials" would definitely be a good thing to include.
For example, "The name of the property displayed in the ArgumentOutOfRangeException in the MaxDeliveryCount property in SubscriptionProperties was updated to use the correct property name." does not qualify as an important bug fix so shouldn't be listed under `Bugs Fixed` but can be listed under `Other Changes`. However, "Added a new overload to the constructor to support AzureAD credentials" would be a good thing to include under `Features Added`.

Ensure the release notes are written from the perspective of the user. We don't want to tell them about a new change without ALSO telling them how to take advantage of the change with either a link to the documentation or a short snippet of code.

Expand Down
16 changes: 8 additions & 8 deletions docs/policies/releases.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -115,20 +115,20 @@ In order for consistency across our SDKs and to enable automation to validate an
- <Deprecated: for soon-to-be removed features>
- <Removed: for now removed features>

### Key Bugs Fixed
- <for important bug fixes to be called out in release notes>
### Bugs Fixed
- <for important bug fixes to be called out in release notes, especially for fixes that the developer will notice or need to react to in some way>
- <Security: for any security fixes>

### Fixed
- <for any bug fixes that are not important enough to include in release notes>
### Other Changes
- <for any bug fixes or other changes that are not important enough to include in release notes>

...
## <older version> (<Release Date>)
- <content/changes for the older release>

... older release details trail off into history below
```
In order to automatically pull the relevant content (see mentions of release notes above) from the change log entries to produce our release notes the formatting of the headers needs to exactly match the format above (i.e. `### Features Added`, `### Breaking Changes`, `### Key Bugs Fixed`). For more details on the general release notes see the [Release Notes Guidance](https://azure.github.io/azure-sdk/policies_releasenotes.html#whats-a-developer-impacting-change).
In order to automatically pull the relevant content (see mentions of release notes above) from the change log entries to produce our release notes the formatting of the headers needs to exactly match the format above (i.e. `### Features Added`, `### Breaking Changes`, `### Bugs Fixed`). For more details on the general release notes see the [Release Notes Guidance](https://azure.github.io/azure-sdk/policies_releasenotes.html#whats-a-developer-impacting-change).

For more information on general change log guidelines see [keep a changelog](https://keepachangelog.com/en/1.0.0/).

Expand All @@ -144,7 +144,7 @@ Example change log:
### Breaking Changes
- Support using SAS token from connection string

### Key Bugs Fixed
### Bugs Fixed
- Issue where AccountName on BlobUriBuilder would not be populated
for non-IP style Uris ([#8638](https://github.com/Azure/azure-sdk-for-net/issues/8638))

Expand All @@ -154,11 +154,11 @@ Example change log:
- Number of operations and models to better align with other client
libraries and the .NET Framework Design Guidelines

### Fixed
### Other Changes
- Parallel upload/download performance improvements
```

{% include requirement/SHOULD %} link to GitHub issues (full URL) that were fixed in that release going forward (i.e. do not backfill older issues). See example above under the `### Key Bugs Fixed` heading.
{% include requirement/SHOULD %} link to GitHub issues (full URL) that were fixed in that release going forward (i.e. do not backfill older issues). See example above under the `### Bugs Fixed` heading.

For clarity, a `change log entry` is simply the header + content up to the next release header OR EOF. During release, if there exists a changelog entry with a version specifier _matching_ that of the currently releasing package, that changelog entry will be added as the body of the GitHub release.

Expand Down