Write changelog for upcoming release #255

JordanMartinez · 2021-01-11T20:55:15Z

Description of the change

Initial draft for what the v0.5.0 (i.e. v0.14.0 PS release-compatible) release notes should be.

Part of purescript/purescript#3985

Checklist:

Added the change to the changelog's "Unreleased" section with a reference to this PR (e.g. "- Made a change (#0000)")
Linked any existing issues or proposals that this pull request should close
Updated or added relevant documentation
Added a test for the contribution (if applicable)

JordanMartinez · 2021-01-11T20:55:41Z

I'm assuming we'll want a meta-issue to track which repos have had their changelog written.

hdgarrood · 2021-01-11T23:19:11Z

I've just spotted that this repo has a v4.1.1 release which isn't mentioned in the changelog, that should probably be fixed. These release notes also don't mention #229, are you still working on them?

JordanMartinez · 2021-01-12T01:00:34Z

No, I didn't include #229 because I believe we reverted that change in #233 / #232.

I'll add the 4.1.1 release. It wasn't included because it was just a tag, not an official GH release.

JordanMartinez · 2021-01-12T01:06:36Z

Should we remove unsafeCompare? It was deprecated in v4.1.1.

hdgarrood · 2021-01-12T01:14:11Z

We reverted the change to ap but we did still move the Applicative superclass law from Monad to Bind.

JordanMartinez · 2021-01-12T02:16:27Z

Ah... Gotcha. I've added that to this PR.

milesfrain · 2021-01-12T02:31:36Z

CHANGELOG.md

+- Added `lift2` example using `Maybe` (#213)
+- Added `const` example (#214)
+- Added `power` example (#253)
+- Improve documentation in various things (#217)
+    - Clarify `Array`'s `do notation`
+    - Clarify purpose of `Monoid` and `Semigroup` newtypes
+- Clarify `Unit` representation in FFI code (#223)


I don't know if this level of detail (where each PR is mentioned) is necessary for changelogs. It would probably be fine to just write something like "Added more examples" or not even mention that, since it doesn't really affect existing users of the library.
I think the main purpose of the changelog is to help folks quickly review API changes since their last update.

I'm good with making this change if others agree. I thought "Added more docs" or something wasn't that helpful either.

I think it's reasonable to point out documentation updates, but I agree they ought to be as concise as possible. For example:

Other improvements: - Added examples to documentation comments for `lift2`, `const`, and `power` (#213, #214, #253) - Improved documentation for `do` notation for `Array`, the purpose of the `Monoid` and `Semigroup` newtypes, and the representation of `Unit` in FFI code (#217, #223)

(They're already de-prioritized by being bundled under the "Other improvements" section, which is easier to skip if you're only skimming for API changes)

I disagree, I think almost every PR should be referenced in the changelog. It's not as if there's a massive amount of detail to wade through here, and it's important that we provide credit to contributors for the changes of theirs we've merged.

Personally I think having separate bullet points for each of the separate documentation PRs (as you do currently) is ideal. We can group them all under a "Documentation improvements" heading so that people who aren't interested in anything that doesn't affect the actual API can easily skim past them.

I agree almost all pull requests should be referenced in the changelog. I'm also fine with bullet points for each documentation PR.

As a note, the more concise version I added doesn't drop any PRs, it just allows some of them to be included in the same line if they're logically related. I also think that's fine, but we should probably have an agreed-upon default.

thomashoneyman

I think others should have a chance to read this changelog and weigh in on its contents, so we should wait for a second review before merging. That said, a 👍 as far as I'm concerned and thank you for getting this started.

hdgarrood · 2021-01-12T12:12:39Z

CHANGELOG.md

+- Added `const` example (#214)
+- Added `power` example (#253)
+- Improve documentation in various things (#217)
+    - Clarify `Array`'s `do notation`


The phrase "do notation" isn't code, so we shouldn't use backticks for it here.

hdgarrood · 2021-01-12T12:15:36Z

CHANGELOG.md

+## [v5.0.0](https://github.com/purescript/purescript-prelude/releases/tag/v4.1.0) - 2021-MONTH-DATE
+
+Breaking changes:
+- Make library compile on `v0.14.0` (#206)


I would suggest phrasing this as "Support compiler version v0.14.0, and drop support for previous versions", as it's a bit more clear that v0.14.0 refers to the compiler version that way as opposed to the version of some other tool, and also it means that it's clear that this version of the library can't be used with older compilers.

hdgarrood · 2021-01-12T12:19:06Z

Let's remove unsafeCompare, it has already been deprecated for over a year.

JordanMartinez · 2021-01-13T01:47:38Z

@hdgarrood I've addressed the feedback you raised.

JordanMartinez · 2021-01-13T15:00:09Z

Any other feedback? Or am I clear to merge this?

hdgarrood · 2021-01-13T16:36:24Z

CHANGELOG.md

+- Improve documentation in various things (#217)
+    - Clarify `Array`'s "do notation"
+    - Clarify purpose of `Monoid` and `Semigroup` newtypes


I think having a bullet point labelled "improve documentation in various things" under a parent "Documentation improvements" is a bit redundant. How about:

Suggested change

- Improve documentation in various things (#217)

- Clarify `Array`'s "do notation"

- Clarify purpose of `Monoid` and `Semigroup` newtypes

- Clarify `Array`'s do notation and the purposes of `Monoid` and `Semigroup` newtypes (#217)

hdgarrood · 2021-01-13T16:37:09Z

I would like to go over the commits since 4.1.1 just to make sure we haven't missed anything out, but other than that, this looks good to me. Thanks!

hdgarrood · 2021-01-13T16:42:20Z

I think the following PRs should be referenced in this changelog: #220, #227, #238

JordanMartinez · 2021-01-13T20:16:27Z

Added those PRs. How about now?

hdgarrood · 2021-01-13T20:33:02Z

CHANGELOG.md

@@ -12,6 +12,41 @@ Bugfixes:

 Other improvements:

+## [v5.0.0](https://github.com/purescript/purescript-prelude/releases/tag/v4.1.0) - 2021-MONTH-DATE


Oh, last thing, maybe it would be good to leave this stuff under "Unreleased" for now so that we don't forget to update the placeholder link and date? I don't really mind though.

Makes sense to me. I'll add that change and then merge.

* Write changelog for upcoming release * Add v4.1.1 release to changelog * Document changes that happened in v4.1.1 release * Add purescript#229 to breaking changes * Remove backticks around 'do notation' * Rephrase 'make library compile on v0.14.0' * Separate documentation improvement PRs from other improvements * Include other PR related to v0.14.0 in changelog * Add toRep PR * Put Array do notation and Monoid newtype PR summary on one line * Include PR that fixes typo * Change section header back to Unreleased

Write changelog for upcoming release

65b53cb

JordanMartinez added 2 commits January 11, 2021 17:01

Add v4.1.1 release to changelog

bc0ed12

Document changes that happened in v4.1.1 release

4014134

Add #229 to breaking changes

7a1b9b6

milesfrain reviewed Jan 12, 2021

View reviewed changes

thomashoneyman approved these changes Jan 12, 2021

View reviewed changes

hdgarrood reviewed Jan 12, 2021

View reviewed changes

JordanMartinez added 2 commits January 12, 2021 17:43

Remove backticks around 'do notation'

e5e948a

Rephrase 'make library compile on v0.14.0'

4afb2bd

JordanMartinez mentioned this pull request Jan 13, 2021

Remove deprecated unsafeCompare #256

Closed

Separate documentation improvement PRs from other improvements

26a197d

hdgarrood reviewed Jan 13, 2021

View reviewed changes

JordanMartinez added 4 commits January 13, 2021 12:10

Include other PR related to v0.14.0 in changelog

321b5f9

Add toRep PR

b0ec190

Put Array do notation and Monoid newtype PR summary on one line

4c606f8

Include PR that fixes typo

4b978f1

hdgarrood reviewed Jan 13, 2021

View reviewed changes

hdgarrood approved these changes Jan 13, 2021

View reviewed changes

Change section header back to Unreleased

c35562b

JordanMartinez merged commit d54fbf7 into purescript:master Jan 13, 2021

JordanMartinez deleted the writeChangelog branch January 13, 2021 20:36

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Write changelog for upcoming release #255

Write changelog for upcoming release #255

JordanMartinez commented Jan 11, 2021 •

edited

Loading

JordanMartinez commented Jan 11, 2021

hdgarrood commented Jan 11, 2021

JordanMartinez commented Jan 12, 2021

JordanMartinez commented Jan 12, 2021

hdgarrood commented Jan 12, 2021

JordanMartinez commented Jan 12, 2021

milesfrain Jan 12, 2021

JordanMartinez Jan 12, 2021

thomashoneyman Jan 12, 2021

thomashoneyman Jan 12, 2021 •

edited

Loading

hdgarrood Jan 12, 2021

hdgarrood Jan 12, 2021

thomashoneyman Jan 12, 2021

thomashoneyman left a comment

hdgarrood Jan 12, 2021

hdgarrood Jan 12, 2021

hdgarrood commented Jan 12, 2021

JordanMartinez commented Jan 13, 2021

JordanMartinez commented Jan 13, 2021

hdgarrood Jan 13, 2021

hdgarrood commented Jan 13, 2021

hdgarrood commented Jan 13, 2021

JordanMartinez commented Jan 13, 2021

hdgarrood Jan 13, 2021

JordanMartinez Jan 13, 2021

		@@ -12,6 +12,41 @@ Bugfixes:

		Other improvements:

		## [v5.0.0](https://github.com/purescript/purescript-prelude/releases/tag/v4.1.0) - 2021-MONTH-DATE

Write changelog for upcoming release #255

Write changelog for upcoming release #255

Conversation

JordanMartinez commented Jan 11, 2021 • edited Loading

JordanMartinez commented Jan 11, 2021

hdgarrood commented Jan 11, 2021

JordanMartinez commented Jan 12, 2021

JordanMartinez commented Jan 12, 2021

hdgarrood commented Jan 12, 2021

JordanMartinez commented Jan 12, 2021

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

thomashoneyman Jan 12, 2021 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

thomashoneyman left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

hdgarrood commented Jan 12, 2021

JordanMartinez commented Jan 13, 2021

JordanMartinez commented Jan 13, 2021

Choose a reason for hiding this comment

hdgarrood commented Jan 13, 2021

hdgarrood commented Jan 13, 2021

JordanMartinez commented Jan 13, 2021

Choose a reason for hiding this comment

Choose a reason for hiding this comment

JordanMartinez commented Jan 11, 2021 •

edited

Loading

thomashoneyman Jan 12, 2021 •

edited

Loading