search

purescript / documentation

Documentation for the PureScript language, compiler, and tools.
Other
1.02k stars 301 forks source link

Add all changelog entries for breaking changes in PureScript 0.15.0 #426

Closed JordanMartinez closed 2 years ago

JordanMartinez commented 2 years ago

This PR adds all the changelog entries across core, contrib, web, and node libraries from the v0.15.0 ecosystem update. Only relevant (i.e. useful to end-users, not necessarily maintainers) content is included.

The content here can and should diverge from the original changelog entry when this version can provide more context/instructions on how to migrate things well.

Unresolved questions/issues:

thomashoneyman commented 2 years ago

Dropping support for color schemes in the 'colors' repo wasn't included in its changelog entry because it was already done in a prior release. Should it be added here?

I don’t think we should include this, both because it happened in a prior release and because it’s only just become a contributor library.

In general I think we should only include changes that we think are likely to affect a good number of users (ie. a small breaking change to purescript-uri wouldn’t need to be included), and we should prioritize core libraries over contrib libraries — officially, the core team only updates core libraries for the release. We just update the others to make it a smooth transition.

thomashoneyman commented 2 years ago

In keeping with my review comments above, I think this is way too much content for the guide and we need to trim it back.

It may be that we should create a separate document that aggregates changelogs across all libraries (which is how this content reads). That seems valuable to me.

But I don’t think it’s the right fit for the migration guide, which should be opinionated about what changes are important and which should give you advice on how to update your code.

JordanMartinez commented 2 years ago

It may be that we should create a separate document that aggregates changelogs across all libraries (which is how this content reads). That seems valuable to me.

I was thinking the same thing when I saw how long the guide becomes when this gets added. It has value, but I agree with you that the main goal of the migration guide is to tell people how to fix broken code.

I was wondering if perhaps there should be a folder for the migration guide storing two files. The first file being the current migration guide. The second being the ecosystem update release notes.

thomashoneyman commented 2 years ago

I was thinking the same thing when I saw how long the guide becomes when this gets added. It has value, but I agree with you that the main goal of the migration guide is to tell people how to fix broken code.

Yea. I think we should use the previous migration guide as the template for this migration guide: https://github.com/purescript/documentation/blob/master/migration-guides/0.14-Migration-Guide.md

I was wondering if perhaps there should be a folder for the migration guide storing two files. The first file being the current migration guide. The second being the ecosystem update release notes.

Yea, we could have say a 0.15-Migration-Guide.md and 0.15-Ecosystem-Changelog.md or something like that. How are you getting these changelogs appended together? It would be nice to have that saved somewhere if we're going to start doing this every year.

JordanMartinez commented 2 years ago

Note to self about math: https://github.com/purescript/package-sets/pull/1075#issuecomment-1080996792=

JordanMartinez commented 2 years ago

I've updated this PR to just include the full unabbreviated release notes as a separate file.

I'll open a separate PR that focuses on how to actually update broken code.

JordanMartinez commented 2 years ago

Note: there are still the affjax changelog entries. If there are other breaking changes added later, it'll be easy to update this.