Framework: Update "Maintaining Changelogs" section to current recommendations

[aduth]

Related:

• #core-js Meeting discussion (link requires registration) (summary)
• Update the npm packages release process #14136

This pull request seeks to update the packages document "Maintaining Changelogs" section, as the information was no longer accurate as of the revised packages release process implemented in #14136. It now describes how a developer should not choose the version, but instead add changes under a relevant subsection in a "Master" heading at the top of the file. It also includes specific mentions of the common subsections used in changelogs (breaking change, new feature, etc).

Testing Instructions:

Documentation-only changes. There is no impact on the application.

[gziolo]

Great work, it’s all nicely explained and much better aligns with how we approach the process these days 👍

[nerrad]

Love it 👍 ! I would like to see the inclusion of links to pulls for each change too.

[ntwb]

@nerrad This can be quite time consuming and cumbersome, considering the changelog requirements are to include the proposed changelog entry in the pull request the PR number is not known at this stage, as such a follow up commit is required for each PR submitted.

[nerrad]

PR number is not known at this stage, as such a follow up commit is required for each PR submitted.

Which is what I've been doing. I agree it's a bit of a chore, but the question is whether the benefits (having an easy reference to the pull implementing the change) outweigh the negatives (doing an extra commit adding the link). I can't answer that for everyone, but for me I find it super useful and the benefits outweigh the chore.

Yes I know git history can be used as well.

My suggestion is definitely not a blocker to this getting merged.

[aduth]

I agree with both of you. And I agree it shouldn't block. (It's an agreement party! 😄 )

At this point, I'll be happy if we can get people to add changelog notes at all, before considering how to make it more cumbersome to do so. From there I'd explore enforcement (#13594) and automation separately.