search

stoplightio / elements

Build beautiful, interactive API Docs with embeddable React or Web Components, powered by OpenAPI and Markdown.
https://stoplight.io/open-source/elements/
Apache License 2.0
1.79k stars 205 forks source link

Elements: Automate changelog #2286

Open pamgoodrich opened 1 year ago

pamgoodrich commented 1 year ago

@pamgoodrich commented on Tue Nov 15 2022

Add changelog file and new feature for sidebar sizing (2268.

Also, review contribution guidelines and add step for updating changelog if applicable.

From @pamgoodrich in slack: We just met about the Elements changelog and decided that it would be best to follow the approach we use with Spectral, which would be to automate changelogs for elements-dev-portal and elements, but not elements-core. We would then pull in this content to the Releases tab, which @jakub says can also be automated. He thinks this has other benefits aside from the changelog, but I'll let him discuss that. (Team: if I got something wrong, please correct me.) @Eric Adams

dpashkevich commented 1 year ago

As a consumer of Stoplight Elements, I would love to follow a changelog so that I can learn about major improvements. We've been using Stoplight Elements for over a year, and there have been several precedents where we noticed UI issues with Stoplight Elements embedded into our own Dev Portal, then observed that the issues are not there when going to <workspace.stoplight.io> directly, and updated @stoplight/elements-dev-portal that was N versions behind at that point.

Publishing meaningful release notes (I'm slightly skeptical about having them automatically generated from commits) would allow consumers to be more proactive about keeping their dependency up to date when there are major changes, or when the bug they've been tracking (in this repository) has been fixed. I think it would also encourage people to update the dependency more often and foster greater community participation in this project on GitHub.

zebapy commented 8 months ago

I would recommend at least a minimal - even manually curated - changelog https://keepachangelog.com/en/1.1.0/ It's hard to consume or keep up to date with this without knowing what's been released.