Update changelog on main #5092

andrross · 2022-11-04T23:29:23Z

This branch copies the release notes from 2.4 and removes all the redundant entries from the changelog on main. All the remaining entries in the changelog should reflect changes intended for 3.0.

Signed-off-by: Andrew Ross andrross@amazon.com

Check List

New functionality includes testing.
- All tests pass
New functionality has been documented.
- New functionality has javadoc added
Commits are signed per the DCO using --signoff
Commit changes are listed out in CHANGELOG.md file (See: Changelog)

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.
For more information on following Developer Certificate of Origin and signing off your commits, please check here.

github-actions · 2022-11-05T00:00:53Z

Gradle Check (Jenkins) Run Completed with:

RESULT: UNSTABLE ❌
URL: https://build.ci.opensearch.org/job/gradle-check/6413/
CommitID: 28bb684
Please examine the workflow log, locate, and copy-paste the failure below, then iterate to green.
Is the failure a flaky test unrelated to your change?

github-actions · 2022-11-07T20:42:42Z

Gradle Check (Jenkins) Run Completed with:

RESULT: FAILURE ❌
URL: https://build.ci.opensearch.org/job/gradle-check/6462/
CommitID: dcf8c24
Please examine the workflow log, locate, and copy-paste the failure below, then iterate to green.
Is the failure a flaky test unrelated to your change?

dblock

A few asks below. Thanks for working through this!

dblock · 2022-11-07T21:59:38Z

CHANGELOG.md

+avoid a painful and error-prone process of attempting to compile the release
+notes at release time. On each release the "unreleased" entries of the
+changelog are moved to the appropriate release notes document in the
+`./release-notes` folder.


Remove the line wrap as we do in all markdown files.

dblock · 2022-11-07T22:00:07Z

CHANGELOG.md

-## [Unreleased]
+## FAQ
+### What is the purpose of the changelog?
+The purpose of the changelog is for the contributors and maintainers to


The other reason is to make the CHANGELOG available during development, add?

dblock · 2022-11-07T22:00:29Z

CHANGELOG.md

+ - Dependency updates
+ - Fixes for security issues
+
+The following are some examples where a changelog entry  is not necessary:


Remove double space after entry.

dblock · 2022-11-07T22:01:50Z

CHANGELOG.md


-## [2.x]
+## [Unreleased 2.x]


So why wouldn't we remove this from main and only have changes that go to 3.0 right now?

It seems simpler to me to keep the changes here and backport them, so that it works the same way as all other changes in the PR. This way, when we do a release we can move this whole section to a release-notes-2.5.0.md file on main and backport it to the 2.x and 2.5 branch and it all just works (I hope).

Do you find this confusing? I don't love the idea of having to make a backport PR different by including the changelog line.

I think you're right.

dblock · 2022-11-07T22:04:20Z

CHANGELOG.md

+document. The changelog on the `main` branch will contain sections for the _next
+major_ and _next minor_ releases. Your entry should go into the section it is
+intended to be released in. In practice, most changes to `main` will be backported
+to the next minor release so most entries will likely be in that section.


Maybe say that clearer that changes that you plan to backport should be put in the unreleased 2.x section?

We also need to accommodate scenarios where the backport behaves differently (e.g. option x added, backported as x=false to 2.x, but turned on as x=true in 3.0). Not sure if it's worth calling out?

re: backport behaves differently

I'd probably not call this out. In general, I suspect this would be modeled as two separate PRs anyway, i.e. "introduce option x" is done first and is backported, then a separate change ("make x the default behavior") is made and not backported.

rursprung · 2022-11-08T06:59:42Z

CHANGELOG.md

+`./release-notes` folder.
+
+### Which changes require a CHANGELOG entry?
+Changelogs are intended for _users_. In short, any change that a user of


i know that i've also used the word "user" before in this context, but i think it's a hard-to-define word here: does this mean the operator of an OpenSearch cluster? or does it mean the developer interacting with OpenSearch through APIs/libraries? or does it mean the (business) end-user interacting with it through OpenSearch Dashboards?

IMHO it should mean all of those, but maybe a short description of what is meant might be helpful to avoid people taking assumptions on the definition of this word and then skipping changelog entries which would've made sense?

Thanks @rursprung. I've reworded this section so place take a look and let me know what you think.

github-actions · 2022-11-08T17:29:11Z

Gradle Check (Jenkins) Run Completed with:

RESULT: FAILURE ❌
URL: https://build.ci.opensearch.org/job/gradle-check/6582/
CommitID: 9d90a15
Please examine the workflow log, locate, and copy-paste the failure below, then iterate to green.
Is the failure a flaky test unrelated to your change?

rursprung · 2022-11-08T17:40:08Z

CHANGELOG.md

+The purpose of the changelog is for the contributors and maintainers to incrementally build the release notes throughout the development process to avoid a painful and error-prone process of attempting to compile the release notes at release time. On each release the "unreleased" entries of the changelog are moved to the appropriate release notes document in the `./release-notes` folder. Also, incrementally building the changelog provides a concise, human-readable list of significant features that have been added to the unreleased version under development.
+
+### Which changes require a CHANGELOG entry?
+Changelogs are intended for operators/administrators, developers integrating with libraries and APIs, and end-users interacting with OpenSearch Dashboards and/or the REST API. In short, any change that a user of OpenSearch might want to be aware of should be included in the changelog. The changelog is _not_ intended to replace the git commit log that developers of OpenSearch itself rely upon. The following are some examples of changes that should be in the changelog:


thanks, this already looks very nice! maybe, just as nit-picking (note: english is not my native language!), how about this (just so that every last one understands it)?

Suggested change

Changelogs are intended for operators/administrators, developers integrating with libraries and APIs, and end-users interacting with OpenSearch Dashboards and/or the REST API. In short, any change that a user of OpenSearch might want to be aware of should be included in the changelog. The changelog is _not_ intended to replace the git commit log that developers of OpenSearch itself rely upon. The following are some examples of changes that should be in the changelog:

Changelogs are intended for operators/administrators, developers integrating with libraries and APIs, and end-users interacting with OpenSearch Dashboards and/or the REST API (collectively referred to as "user"). In short, any change that a user of OpenSearch might want to be aware of should be included in the changelog. The changelog is _not_ intended to replace the git commit log that developers of OpenSearch itself rely upon. The following are some examples of changes that should be in the changelog:

Sure thing, added that text

github-actions · 2022-11-08T17:43:37Z

Gradle Check (Jenkins) Run Completed with:

RESULT: SUCCESS ✅
URL: https://build.ci.opensearch.org/job/gradle-check/6580/
CommitID: f19b809

github-actions · 2022-11-08T17:57:42Z

Gradle Check (Jenkins) Run Completed with:

RESULT: SUCCESS ✅
URL: https://build.ci.opensearch.org/job/gradle-check/6583/
CommitID: 7112621

andrross · 2022-11-08T18:19:46Z

I moved the process instructions to the changelog section in CONTRIBUTING.md and out of the changelog itself

dblock · 2022-11-08T18:25:43Z

I am going to merge this given it's all MD files, no need to wait for gradle check.

rursprung · 2022-11-08T18:21:57Z

CHANGELOG.md

@@ -1,68 +1,14 @@
 # CHANGELOG

-Inspired from [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)


i'd keep that line. or rather, i'd change it to this:

All notable changes to this project are documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

rursprung · 2022-11-08T18:23:46Z

CHANGELOG.md


-## [Unreleased]
+## [Unreleased 3.0]


just spotted this (sorry that i didn't see this the first time around):
these brackets are here to turn this into a link (the URL should be defined at the end of the document; at least that's the case in the currently integrated document). i don't see you defining/changing the URL anywhere. same goes for the other such headers which you changed & also the new document. accordingly, these are no longer links.
please fix.

I can escape the brackets here. In the other file these are in backticks so I don't believe markdown will attempt to interpret them as links.

(though the example from keepachangelog.com uses these unescaped brackets as version headers)

the example from keepachangelog.com has the links defined at the very end. the same is the case for the current version of the changelog here in OpenSearch and i think it should be kept this way

Oh of course, I had missed that! Our branching strategy makes this very difficult to do. For example, commits on main include a mix of things that are backported to a 2.x release and things that will only go in 3.0. I don't know how to get a clean commit history that correspond to these labels.

rursprung · 2022-11-08T18:25:38Z

CONTRIBUTING.md

-As a contributor, you must ensure that every pull request has the changes listed out within the corresponding version and appropriate section of [CHANGELOG](CHANGELOG.md) file.
+- Adding, modifying, or fixing tests
+- An incremental PR for a larger feature (such features should include _one_
+  changelog entry for the feature)


AFAIR you got a review feedback before elsewhere saying that these linebreaks should be avoided?

github-actions · 2022-11-08T18:29:56Z

Gradle Check (Jenkins) Run Completed with:

RESULT: SUCCESS ✅
URL: https://build.ci.opensearch.org/job/gradle-check/6590/
CommitID: 77693f9

github-actions · 2022-11-08T18:54:25Z

Gradle Check (Jenkins) Run Completed with:

RESULT: SUCCESS ✅
URL: https://build.ci.opensearch.org/job/gradle-check/6592/
CommitID: c6ab847

codecov-commenter · 2022-11-08T18:56:54Z

Codecov Report

Merging #5092 (c6ab847) into main (fab4336) will increase coverage by 0.10%.
The diff coverage is 66.34%.

❗ Current head c6ab847 differs from pull request most recent head 5ff0032. Consider uploading reports for the commit 5ff0032 to get more accurate results

@@             Coverage Diff              @@
##               main    #5092      +/-   ##
============================================
+ Coverage     70.84%   70.95%   +0.10%     
- Complexity    57867    58177     +310     
============================================
  Files          4692     4708      +16     
  Lines        276650   277557     +907     
  Branches      40155    40188      +33     
============================================
+ Hits         196002   196929     +927     
+ Misses        64500    64494       -6     
+ Partials      16148    16134      -14

Impacted Files	Coverage Δ
...java/org/opensearch/upgrade/ValidateInputTask.java	`84.61% <0.00%> (ø)`
...ch/analysis/common/CommonAnalysisModulePlugin.java	`92.33% <0.00%> (+0.05%)`	⬆️
...mon/HyphenationCompoundWordTokenFilterFactory.java	`0.00% <0.00%> (ø)`
...index/analysis/IcuCollationTokenFilterFactory.java	`59.25% <0.00%> (-2.28%)`	⬇️
.../src/main/java/org/opensearch/LegacyESVersion.java	`59.34% <ø> (-2.37%)`	⬇️
...ecommission/awareness/put/DecommissionRequest.java	`85.71% <0.00%> (-6.60%)`	⬇️
...min/cluster/stats/TransportClusterStatsAction.java	`70.83% <ø> (ø)`
...ensearch/action/search/SearchTransportService.java	`86.80% <ø> (-0.20%)`	⬇️
...va/org/opensearch/action/update/UpdateRequest.java	`43.92% <0.00%> (-0.52%)`	⬇️
...arch/cluster/decommission/DecommissionService.java	`35.65% <0.00%> (+0.38%)`	⬆️
... and 634 more

Help us with your feedback. Take ten seconds to tell us how you rate us. Have a feature suggestion? Share it here.

dblock · 2022-11-08T18:57:19Z

@andrross saw some new comments above, LMK when this is good to go?

rursprung · 2022-11-08T19:03:09Z

CHANGELOG.md

 ### Security
-[Unreleased]: https://github.com/opensearch-project/OpenSearch/compare/2.2.0...HEAD


ah, just spotted it: here you are removing the links. IMHO you should keep them and adapt them to the new name

I've added these links back. Though for the reasons I listed above I'm not sure how useful they are. We can look to improve this as a separate task though.

This branch copies the release notes from 2.4 and removes all the redundant entries from the changelog on main. All the remaining entries in the changelog should reflect changes intended for 3.0. This also adds an FAQ detailing how the changelog should work with our branching strategy. Signed-off-by: Andrew Ross <andrross@amazon.com>

github-actions · 2022-11-08T19:15:44Z

Gradle Check (Jenkins) Run Completed with:

RESULT: UNSTABLE ❌
URL: https://build.ci.opensearch.org/job/gradle-check/6601/
CommitID: 5ff0032
Please examine the workflow log, locate, and copy-paste the failure below, then iterate to green.
Is the failure a flaky test unrelated to your change?

github-actions · 2022-11-08T19:37:43Z

Gradle Check (Jenkins) Run Completed with:

RESULT: UNSTABLE ❌
URL: https://build.ci.opensearch.org/job/gradle-check/6602/
CommitID: d7c1db3
Please examine the workflow log, locate, and copy-paste the failure below, then iterate to green.
Is the failure a flaky test unrelated to your change?

github-actions · 2022-11-08T19:41:54Z

Gradle Check (Jenkins) Run Completed with:

RESULT: SUCCESS ✅
URL: https://build.ci.opensearch.org/job/gradle-check/6603/
CommitID: 3ee99ea

This branch copies the release notes from 2.4 and removes all the redundant entries from the changelog on main. All the remaining entries in the changelog should reflect changes intended for 3.0. This also adds an FAQ detailing how the changelog should work with our branching strategy. Signed-off-by: Andrew Ross <andrross@amazon.com> Signed-off-by: Andrew Ross <andrross@amazon.com> Signed-off-by: Andriy Redko <andriy.redko@aiven.io>

This also removes a Jackson dependency update from the changelog because it was backported all the way back to 2.4 so therefore is not unreleased here any more. Signed-off-by: Andrew Ross <andrross@amazon.com>

This also removes a Jackson dependency update from the changelog because it was backported all the way back to 2.4 so therefore is not unreleased here any more. Signed-off-by: Andrew Ross <andrross@amazon.com> Signed-off-by: Andrew Ross <andrross@amazon.com>

andrross marked this pull request as ready for review November 4, 2022 23:29

andrross requested review from a team and reta as code owners November 4, 2022 23:29

kotwanikunal approved these changes Nov 7, 2022

View reviewed changes

andrross force-pushed the changelog-update-main branch from 28bb684 to dcf8c24 Compare November 7, 2022 20:11

andrross mentioned this pull request Nov 7, 2022

[PROPOSAL] Author CHANGELOG in each PR instead of collecting them in the last days before a release #1868

Closed

dblock requested changes Nov 7, 2022

View reviewed changes

rursprung reviewed Nov 8, 2022

View reviewed changes

andrross force-pushed the changelog-update-main branch 3 times, most recently from 9d90a15 to 7112621 Compare November 8, 2022 17:25

rursprung reviewed Nov 8, 2022

View reviewed changes

andrross force-pushed the changelog-update-main branch from 7112621 to 77693f9 Compare November 8, 2022 18:00

dblock approved these changes Nov 8, 2022

View reviewed changes

andrross force-pushed the changelog-update-main branch from 77693f9 to c6ab847 Compare November 8, 2022 18:18

dblock approved these changes Nov 8, 2022

View reviewed changes

rursprung reviewed Nov 8, 2022

View reviewed changes

andrross force-pushed the changelog-update-main branch from c6ab847 to 5ff0032 Compare November 8, 2022 18:40

rursprung reviewed Nov 8, 2022

View reviewed changes

andrross force-pushed the changelog-update-main branch from 5ff0032 to d7c1db3 Compare November 8, 2022 19:07

andrross force-pushed the changelog-update-main branch from d7c1db3 to 3ee99ea Compare November 8, 2022 19:09

dblock approved these changes Nov 8, 2022

View reviewed changes

dblock merged commit 90fefa2 into opensearch-project:main Nov 8, 2022

andrross deleted the changelog-update-main branch November 9, 2022 19:10

		@@ -1,68 +1,14 @@
		# CHANGELOG

		Inspired from [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)

		### Security
		[Unreleased]: https://github.com/opensearch-project/OpenSearch/compare/2.2.0...HEAD

Update changelog on main #5092

Update changelog on main #5092

Conversation

andrross commented Nov 4, 2022

Check List

github-actions bot commented Nov 5, 2022

Gradle Check (Jenkins) Run Completed with:

github-actions bot commented Nov 7, 2022

Gradle Check (Jenkins) Run Completed with:

dblock left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

github-actions bot commented Nov 8, 2022

Gradle Check (Jenkins) Run Completed with:

Choose a reason for hiding this comment

Choose a reason for hiding this comment

github-actions bot commented Nov 8, 2022

Gradle Check (Jenkins) Run Completed with:

github-actions bot commented Nov 8, 2022

Gradle Check (Jenkins) Run Completed with:

andrross commented Nov 8, 2022

dblock commented Nov 8, 2022

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

github-actions bot commented Nov 8, 2022

Gradle Check (Jenkins) Run Completed with:

github-actions bot commented Nov 8, 2022

Gradle Check (Jenkins) Run Completed with:

codecov-commenter commented Nov 8, 2022

Codecov Report

dblock commented Nov 8, 2022

Choose a reason for hiding this comment

Choose a reason for hiding this comment

github-actions bot commented Nov 8, 2022

Gradle Check (Jenkins) Run Completed with:

github-actions bot commented Nov 8, 2022

Gradle Check (Jenkins) Run Completed with:

github-actions bot commented Nov 8, 2022

Gradle Check (Jenkins) Run Completed with: