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: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
