Skip to content

Improve changelog design #7253

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Merged
merged 10 commits into from
Mar 10, 2021
Merged

Improve changelog design #7253

merged 10 commits into from
Mar 10, 2021

Conversation

mtrezza
Copy link
Member

@mtrezza mtrezza commented Mar 7, 2021 •
edited
Loading

New Pull Request Checklist

Issue Description

Changelog redesign

Related issue: closes #7252

Approach

Improved design inspired by Node.js changelog.

  • Added a version table
  • Condensed entry by removing link to contributor, instead letting the contributor add their GitHub handle or real name as plain text; GitHub handles are not persistent anyway and break if the user changes their name, see docs; new entry format:

    [Description] ([Contributor]) #[Link to PR]
    Added something new (David Hume) #1711

  • Release section contains following headlines:
    • Breaking Changes
      • Any change that is breaking, regardless of what the change is about; for example it can be a bug fix or a new feature that replaces old functionality
    • Notable Changes
      • New important or useful features or improvements, but never bug fixes, unless published security vulnerabilities.
      • Security vulnerabilities should be mentioned with their CVS ID.
    • Bug Fixes
      • All bug fixes, unless it's a breaking fix, then it goes under "Breaking Changes".
    • Other Commits
      • Any minor changes, small improvement, bug fixes (unless published security vulnerability).

TODOs before merging

(none)

@codecov
Copy link

codecov bot commented Mar 7, 2021 •
edited
Loading

Codecov Report

Merging #7253 (43be542) into master (de50b7b) will not change coverage.
The diff coverage is n/a.

Impacted file tree graph

@@           Coverage Diff           @@
##           master    #7253   +/-   ##
=======================================
  Coverage   94.03%   94.03%           
=======================================
  Files         172      172           
  Lines       12970    12970           
=======================================
  Hits        12196    12196           
  Misses        774      774
Impacted Files Coverage Δ
src/RestWrite.js 93.84% <0.00%> (ø)

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update de50b7b...85dd4be. Read the comment docs.

@mtrezza mtrezza requested review from TomWFox, davimacedo and dplewis and removed request for davimacedo March 7, 2021 14:19
@cbaker6
Copy link
Contributor

cbaker6 commented Mar 7, 2021

I like it! Easy to navigate and easy to search for notable changes

@mtrezza
Copy link
Member Author

mtrezza commented Mar 7, 2021 •
edited
Loading

Do you think we should remove the "Bug Fixes" section and just add them to "Other Commits"? That would simplify and I am not sure why we would want to distinguish bug fixes as a separate section or how it serves developers.

@TomWFox
Copy link
Contributor

TomWFox commented Mar 7, 2021

Some much needed TLC, I really like the navigation!

TomWFox
TomWFox reviewed Mar 7, 2021
View reviewed changes
@mtrezza
Copy link
Member Author

mtrezza commented Mar 7, 2021 •
edited
Loading

I have merged the "Bug Fixes" into "Other Commits". The separate section does not seem to provide any additional value for readers, because:

  • A bug fix per se does not say anything about the importance or relevance of the change
  • If the bug fix has high relevance, it can go under "Notable Changes"
  • The distinction between bug fix and a "common change" often seems to be not clear (was it a bug fix, an improvement, etc?), so why bother trying to categorize it
  • Security vulnerability fixes should always go under "Notable Changes" including their CVS ID for reference (unless they are braking of course, then under "Breaking Changes")

This means the headlines are now clearly denoting relevance:

  1. Breaking Changes: upgrade blocker - should not upgrade without taking a look at them
  2. Notable Changes: can upgrade - but it may be beneficial to look at it to not miss out a practical new feature for example
  3. Other Commits: read if you like the details

The maintainer creating the release is also maintaining the changelog and can rearrange items among categories and if necessary optimize the wording of each item description (e.g. if too verbose or unclear) during the final review.

mtrezza
mtrezza commented Mar 8, 2021
View reviewed changes
dblythy
dblythy reviewed Mar 8, 2021
View reviewed changes
dblythy
dblythy reviewed Mar 8, 2021
View reviewed changes
dblythy
dblythy reviewed Mar 8, 2021
View reviewed changes
@dblythy
Copy link
Member

dblythy commented Mar 8, 2021 •
edited
Loading

This looks really good.

Would it perhaps still be worth having a "new features" section, as well as the notable changes? When I read the CHANGELOG I like looking for new and cool things I can implement on my Parse Server.

Edit: I've just realised that's the "notable features section". Disregard my comment.

@mtrezza
Copy link
Member Author

mtrezza commented Mar 8, 2021 •
edited
Loading

Yes, I sugggest Notable rather than New because something can be new but relevant only for 1% of deployments, while something can be an improvement but relevant for 99% of deployments. This gives us more flexibility. Just thinking of @dplewis' improvement of the schema cache, which will very much be a notable change.

davimacedo
davimacedo approved these changes Mar 10, 2021
View reviewed changes
Copy link
Member

@davimacedo davimacedo left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM!

@mtrezza mtrezza merged commit 36c2608 into parse-community:master Mar 10, 2021
TomWFox
TomWFox reviewed Mar 16, 2021
View reviewed changes
@TomWFox
Copy link
Contributor

TomWFox commented Mar 16, 2021

Personally I would also have put some more of the changes in the notable section...

- request.context for afterFind triggers (dblythy) [#7078](https://github.com/parse-community/parse-server/pull/7078)
- LiveQuery support for $and, $nor, $containedBy, $geoWithin, $geoIntersects queries (dplewis) [#7113](https://github.com/parse-community/parse-server/pull/7113)
- Added `requireAnyUserRoles` and `requireAllUserRoles` for Parse Cloud validator (dblythy) [#7097](https://github.com/parse-community/parse-server/pull/7097)
- Added new account lockout policy option `accountLockout.unlockOnPasswordReset` to automatically unlock account on password reset (Manuel Trezza) [#7146](https://github.com/parse-community/parse-server/pull/7146)
- Allow Cloud Validator `options` to be async (dblythy) [#7155](https://github.com/parse-community/parse-server/pull/7155)

What do you think?

@mtrezza
Copy link
Member Author

mtrezza commented Mar 16, 2021 •
edited
Loading

The suggested purpose of Notable Changes is to have a list of significant changes, like:

  • entirely new feature
  • significant improvement, e.g. new sub-feature of an existing feature that could be considered a separate feature in itself
  • Fixed security vulnerability
  • Experimental features (to quickly get feedback for bug fixing and further development)

Like, if we sold Parse Server in a box and had to design the front, what would it say? Probably not that a method is now async or accepts an additional parameter. I think we should keep a high entry barrier for that section, if we populate it inflationary, we will end up with only CI changes and bug fixes in the Other Changes. Every change is important for someone after all.

So from all of the changes you mentioned above, I personally don't see any passing that criteria, but that is just because of the criteria I had in mind for the section - I am open to other suggestions of how to use the Notable Changes section.

We do have a few other PRs in the pipelines, which I see as notable changes, such as:

  • Single schema cache (merged today)
  • Auth Adapter redesign (expected soon to be merged)
  • Defined Schemas with auto migration (expected soon to be merged)
  • OAuth login (in the works)
  • GraphQL subscriptions (in early stages?)

Arul- pushed a commit to Arul-/parse-server that referenced this pull request Mar 25, 2021
@mtrezza @Arul-
Improve changelog design (parse-community#7253)
d6672f1 
* Changelog redesign

* condensed master section

* imrroved wording

* removed user links

* fixed version links

* fixed another version link

* removed verbose heading

* merged "bug fixes" into "other commits"

* fixed typos

* fixed typo in CONTRIBUTING
@parseplatformorg
Copy link
Contributor

🎉 This change has been released in version 5.0.0-beta.1

@parseplatformorg parseplatformorg added the state:released-beta Released as beta version label Nov 1, 2021
@parseplatformorg
Copy link
Contributor

🎉 This change has been released in version 5.0.0

@parseplatformorg parseplatformorg added the state:released Released as stable version label Mar 14, 2022
@mtrezza mtrezza deleted the improve-changelog-design branch March 24, 2022 18:36
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@dblythy dblythy dblythy left review comments

@TomWFox TomWFox TomWFox left review comments

@davimacedo davimacedo davimacedo approved these changes

@dplewis dplewis Awaiting requested review from dplewis

Assignees
No one assigned
Labels
state:released Released as stable version state:released-beta Released as beta version
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.

Improve changelog design
6 participants
@mtrezza @cbaker6 @TomWFox @dblythy @parseplatformorg @davimacedo