Insufficient guidance in CONTRIBUTING document for feature branches

[dbwiddis]

Is your feature request related to a problem? Please describe.

Pull request checks now fail without an entry in the CHANGELOG. In the "happy path" for commits to main or backports to a version branch, this is a good thing. However, following the same policy for commits to a feature branch may be problematic.

Including the commits in the changelog in the feature branch will pass the check, but will create many merge conflicts in the future when the lines around them are moved to a release.

Describe the solution you'd like

Add documentation to CONTRIBUTING specifying that PRs for a feature branch should be in a separate section. I'm happy to do this, but wanted community concurrence with this plan.

Describe alternatives you've considered

Adding changes inline will create a lot of extra work resolving merge conflicts after a release.

Not documenting feature branch changes will lead to documentation technical debt when the feature is eventually merged to main and the changes must be brought over.

[dbwiddis]

Isn't this should be under Removed?

Good question. I'm not really sure. Some thoughts:

• The Keep a Changelog link that inspires our change log notes that the log should be curated -- otherwise it's no different than a commit diff (from which I sourced this list). I anticipate that there will be a curation step between the current state and the eventual inclusion in the release notes.
• In my view the purpose of a change log is to note changes. Work on a feature branch is primarily "new" work, thus my choice to include the entire list in "added". In my view "removed" would be something that was removed from a previous version of OpenSearch. So the only thing in this list that would fall under "removed" is actual OpenSearch functionality that is changed. In this particular case we're just updating one of the files we added in an earlier PR, so this particular line will probably be curated out (or the PR # combined with an earlier line grouping all actions on the ExtensionsOrchestrator together).

Originally posted by @dbwiddis in #4479 (comment)

[kotwanikunal]

Linking this to the larger discussion within #1868

[peternied]

@kotwanikunal Quick idea -

When on a 'special' branch such as when the name starts with features/* could you alter changeLogPath to be CHANGELOG-FEATUTRE.md. This would avoid merging issues and when it was time to join back up with the mainline the proper enforcement would be in place in the CHANGELOG.md or you could even complain about an existing CHANGELOG-FEATUTRE.md to make sure folks do the right thing.