Update the changelog with release notes for the upcoming v0.14 by kl0tl · Pull Request #3994 · purescript/purescript

kl0tl · 2021-01-21T22:31:14Z

This pull request lists every pull request we merged since v0.13.6 minus those that were already released in v0.13.8 and the following that I took the liberty to omit: #3894, #3934, #3945, #3969, #3976.

I tried to motivate and detail most of the changes, except under the Docs and Internal sections where I only rewrote commit messages when necessary.

thomashoneyman

This is looking great! Thanks for your work, @kl0tl. Just a few comments.

thomashoneyman · 2021-01-22T00:10:20Z

CHANGELOG.md

+Classes can have signatures too, but they must end with the new `Constraint` kind instead of `Type`. For example, `Prim.Row.Cons` now has the signature:
+
+```purescript
+class Cons :: forall k. Symbol -> k -> Row k -> Row k -> Constraint


Previously, Cons had this type:

class Cons (label :: Symbol) (a :: k) (tail :: Row k) (row :: Row k) | label a tail -> row, label row -> a tail

Now, it has this type and also a kind signature, correct?

class Cons :: forall k. Symbol -> k -> Row k -> Row k -> Constraint class Cons (label :: Symbol) (a :: k) (tail :: Row k) (row :: Row k) | label a tail -> row, label row -> a tail

Perhaps it can also be written this way, now that the kind signature is present:

class Cons :: forall k. Symbol -> k -> Row k -> Row k -> Constraint class Cons label a tail row | label a tail -> row, label row -> a tail

It might be useful to include this as a more complete example.

The documentation on Pursuit is confusing. The following class declaration fails to compile because the kind variable isn’t bound:

class Cons (label :: Symbol) (a :: k) (tail :: Row k) (row :: Row k) | label a tail -> row, label row -> a tail

Error found: in module Example at Example.purs:3:36 - 3:37 (line 3, column 36 - line 3, column 37) Type variable k is undefined. while inferring the kind of k while checking that type k has kind Type in type synonym Cons$Dict See https://github.com/purescript/documentation/blob/master/errors/UndefinedTypeVariable.md for more information, or to contribute content related to this error.

It isn’t possible to bind the kind variable with a kind signature, meaning that the following still fails to compile:

class Cons :: forall k. Symbol -> k -> Row k -> Row k -> Constraint class Cons (label :: Symbol) (a :: k) (tail :: Row k) (row :: Row k) | label a tail -> row, label row -> a tail

The kind annotations in the class head must be scrapped, as in your last snippet. The kind signature is not present in the generated documentation though:

Should we display kind signatures in Pursuit when they contain polymorphic kinds? Something like

Ideally we could update Pursuit to display kind signatures containing polymorphic kinds, but I'm not sure it's an easy task 😅

I think we should make updating the HTML docs generation to handle polykinds a priority post-0.14.0. I've usually regretted not being more of a stickler for this in the past when we have added new language features: any information which forms part of a module's API should be present in HTML docs, and I think in an ideal world we would actually not permit merging PRs which add language features until those features are represented properly in HTML docs.

I just found out you already opened #3973 some time ago. Let's tackle this once 0.14 is out then.

CHANGELOG.md

hdgarrood · 2021-01-22T07:13:21Z

This looks great but I think there's too much detail in the polykinds and coercible sections. I think release notes should be easy to skim through, generally I'd say any one change should have no more than one or two short paragraphs. Perhaps we can move some of it into the documentation instead, and link there from here?

hdgarrood · 2021-01-22T07:37:15Z

Hm, on a second reading I actually think the polykinds section is about right, but I do still think there's too much detail in the coercible section. There must be more to this than just "any one change should have no more than one or two short paragraphs" but I haven't yet worked out to express it. I think the detailed rules of when two data types are coercible should be omitted, and we should say what each of the roles mean (nominal, representational, phantom) but the detailed rules for how we infer them could also be omitted.

Perhaps a rule of thumb is that if there's a detail that you don't have to care about as a user of the feature in 90% of cases, it can be omitted. I think for most users, knowing what each of the roles mean is sufficient to have a fairly accurate intuition for what roles will be inferred, for example.

JordanMartinez · 2021-01-23T01:59:00Z

Perhaps we should port some of the Coercible section to the migration guide I'm writing? Then, the release notes can stay smaller, but the detailed explanation can still be read by those who are unfamiliar with what's going on and what more examples.

hdgarrood · 2021-01-23T02:16:47Z

I don't think the migration guide is the right place for this content either, actually. The stuff I think should move is stuff that doesn't matter to users of the feature in the majority of cases, so to me that feels like something that should be kept out of the migration guide as well.

thomashoneyman · 2021-01-23T02:18:03Z

I believe @hdgarrood was suggesting the content be moved into the documentation / language reference.

hdgarrood · 2021-01-23T07:58:23Z

Oh, I just realised I forgot the "repo" in my earlier comment! Yes, I did mean the documentation repo.

JordanMartinez · 2021-01-23T14:01:43Z

Ah! That makes more sense.

CHANGELOG.md

kl0tl · 2021-01-25T08:41:22Z

I replaced the rules followed by the interaction solver and the section about role inference by a small section about roles.

What do you think of replacing the documentation for Prim.Coerce.Coercible on Pursuit with those explanations instead of adding them to the documentation repo? I think the documentation we have now is based on the 2014 version of the paper and not its latest revision from 2016, which does not explain Coercible as a class with compiler-generated instances.

hdgarrood · 2021-01-25T08:54:56Z

Putting the detailed explanations into the documentation for Prim.Coerce.Coercible sounds good to me, although I feel like in any case we should have something in the documentation repo too.

MonoidMusician · 2021-01-25T17:20:45Z

CHANGELOG.md

+foreign import data False :: Boolean
+```
+
+Where the kind `Boolean` and type `Boolean` were two different things. This is no longer the case. The `Prim` kind `Boolean` is now removed, and you can just use `Prim` type `Boolean` in the same way. This is a breaking change.


Can we add a note that we still need the foreign import datas because constructors are not automatically lifted? (i.e. no DataKinds)

I added a note about this after the announce of the deprecation of foreign import kind delcarations.

CHANGELOG.md

kl0tl · 2021-01-28T12:05:43Z

Thank you Ryan for spotting all those typos 🙈

I included #3997 and #3998 in the release notes. I also opened purescript/documentation#371 to document roles, role inference and role annotations in the language reference, and rewrote the documentation of Coercible according to the latest revision of the paper in #3999.

CHANGELOG.md

hdgarrood

Looks great! I'll leave it up to you what you'd like to do with my final two suggestions, and then please feel free to merge.

thomashoneyman

I have a few minor grammatical edits and clarifications, but I think this can (and should) be merged once they are accepted or discussed, along with @hdgarrood's similar comment.

Once again, thank you for putting this together, @kl0tl -- it was clearly a time-consuming task in a significant release!

CHANGELOG.md

kl0tl · 2021-02-16T21:43:11Z

I applied all your suggestions! The latest release of GHC broke my links to the DataKinds and RoleAnnotations extensions so I also updated them. I’d like some feedback on #3994 (comment) and then I’ll merge this 🎉

kl0tl · 2021-02-17T19:59:00Z

Thanks everyone for the reviews !

thomashoneyman reviewed Jan 22, 2021

View reviewed changes

i-am-the-slime reviewed Jan 24, 2021

View reviewed changes