You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@druid.apache.org by GitBox <gi...@apache.org> on 2022/10/06 15:45:19 UTC
[GitHub] [druid] paul-rogers commented on a diff in pull request #13188: process: update PR template to include release notes
paul-rogers commented on code in PR #13188:
URL: https://github.com/apache/druid/pull/13188#discussion_r989212103
##########
CONTRIBUTING.md:
##########
@@ -139,6 +139,32 @@ You can find more developers' resources in [`dev/`](dev) directory.
committer that merges your change will rebase and squash it into a single commit before
committing it to master.
+## Release notes
+
+When you contribute a change, we want to make sure Druid users learn about the change. Give it your best shot! Druid committers will review them as part of the release process.
+
+**Summarize your change.** Describe the user impacting parts of your change, but try to be as concise as you can.
+
+**Be accurate, clear, and concise.** If you can't tick all of these off, the order of priority is accurate > clear > concise.
+
+**WIIFM - what's in it for me?** Spell out why the user should care. A release note shouldn't be like a stand-up update, that focuses on the details of code changes.
+
+**Give enough context.** Make sure there's enough detail for users to do something with the information, if they need to.
+
+**You don't need to be formal and impersonal.** Speak directly to the user ("You can..."). Avoid passive voice (“X has been added”).
+
+### Example release notes
+
+| Template | Examples |
+|-------------------------------------------------|----------|
+| New: You can now… | New: You can now upload CSV files with a single header row for batch ingestion. |
+| Fixed: X no longer does Y when Z. | Fixed: Multi-value string array expressions no longer give flattened results when used in groupBy queries. |
+| Changed: X now does Y. Previously, X did Z. | Changed: The first/last string aggregator now only compares based on values. Previously, the first/last string aggregator’s values were compared based on the `_time` column first and then on values. |
+| Improved: Better / Increased / Updated etc. | Improved: You can now perform Kinesis ingestion even if there are empty shards. Previously, all shards had to have at least one record. |
+| Improved: Better / Increased / Updated etc. | Improved: Java 11 is fully supported and is no longer experimental. Java 17 support is improved. |
+| Deprecated: Removed / Will remove X. | Deprecated: Support for ZooKeeper X.Y will be removed in the next release, so consider upgrading ZooKeeper. |
Review Comment:
These are all great examples. The one item that might be missing is whether the user needs to do anything. For example, on that first one:
> New: You can now upload CSV files with a single header row for batch ingestion. Set the `infrerSchemaFromHeader` property of your Ingestion spec to `true` to enable this feature. See [doc link needed] for the details.
##########
CONTRIBUTING.md:
##########
@@ -139,6 +139,32 @@ You can find more developers' resources in [`dev/`](dev) directory.
committer that merges your change will rebase and squash it into a single commit before
committing it to master.
+## Release notes
+
+When you contribute a change, we want to make sure Druid users learn about the change. Give it your best shot! Druid committers will review them as part of the release process.
+
+**Summarize your change.** Describe the user impacting parts of your change, but try to be as concise as you can.
Review Comment:
Perhaps add:
> A change is user impacting if it:
>
> * Changes what the user sees in the UI.
> * Changes any action that the user takes (in the UI, in the API, in configuration, in install, etc.)
> * Changes the results of any query, ingestion or task.
> * Changes performance (preferably making things faster).
> * Adds or deprecates features.
> * Anything else that changes install, configuration or operation of Druid.
##########
CONTRIBUTING.md:
##########
@@ -139,6 +139,32 @@ You can find more developers' resources in [`dev/`](dev) directory.
committer that merges your change will rebase and squash it into a single commit before
committing it to master.
+## Release notes
+
+When you contribute a change, we want to make sure Druid users learn about the change. Give it your best shot! Druid committers will review them as part of the release process.
Review Comment:
Perhaps:
> Release notes are the way that Druid users will learn of your fix or improvement. What does a user need to know? Druid committers will review and edit your notes. The key is to identify the user impact.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@druid.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@druid.apache.org
For additional commands, e-mail: commits-help@druid.apache.org