Update Contributors libraries according to library guidelines

[thomashoneyman]

@milesfrain, @JordanMartinez, and I have been undertaking an effort to ensure all Contributors libraries meet the Library Guidelines, with the ultimate goal of ensuring these libraries are documented, tested, and welcoming to users as well as potential contributors.

Note: If you are interested in helping maintain any particular libraries, make sure to watch the repository.

This issue tracks progress on at least ensuring the libraries share the same structure, have CI via GitHub Actions, have their latest version published to Pursuit, use Spago for local development, and so on.

Checklist

Please see the library update checklist for the steps to take to update any library in this list.

Initial Library List [ Completed! ]

This list of libraries is our test case to get a feel for how we should update the remaining libraries.

• https://github.com/purescript-contrib/purescript-argonaut
• https://github.com/purescript-contrib/purescript-argonaut-core
• https://github.com/purescript-contrib/purescript-argonaut-traversals
• https://github.com/purescript-contrib/purescript-argonaut-generic
• https://github.com/purescript-contrib/purescript-argonaut-codecs
• https://github.com/purescript-contrib/purescript-ace
• https://github.com/purescript-contrib/purescript-js-timers
• https://github.com/purescript-contrib/purescript-strings-extra
• https://github.com/purescript-contrib/purescript-uri
• https://github.com/purescript-contrib/purescript-machines

Batch 1 [ Completed! ]

This is the first set of libraries to update, which are a bit less-used in case we hit any extra snags.

• https://github.com/purescript-contrib/purescript-freet (PR)
• https://github.com/purescript-contrib/purescript-string-parsers (PR)
• https://github.com/purescript-contrib/purescript-form-urlencoded (PR)
• https://github.com/purescript-contrib/purescript-these (PR)
• https://github.com/purescript-contrib/purescript-options
• https://github.com/purescript-contrib/purescript-http-methods
• https://github.com/purescript-contrib/purescript-precise
• https://github.com/purescript-contrib/purescript-media-types
• https://github.com/purescript-contrib/purescript-fixed-points
• https://github.com/purescript-contrib/purescript-concurrent-queues
• https://github.com/purescript-contrib/purescript-unsafe-reference
• https://github.com/purescript-contrib/purescript-js-date
• https://github.com/purescript-contrib/purescript-now
• https://github.com/purescript-contrib/purescript-nullable

Batch 2 [ Completed! ]

Next, we'll update these more-used libraries:

• https://github.com/purescript-contrib/purescript-arraybuffer-types
• https://github.com/purescript-contrib/purescript-unicode
• https://github.com/purescript-contrib/purescript-pathy
• https://github.com/purescript-contrib/purescript-fork
• https://github.com/purescript-contrib/purescript-formatters
• https://github.com/purescript-contrib/purescript-avar
• https://github.com/purescript-contrib/purescript-aff-bus
• https://github.com/purescript-contrib/purescript-coroutines
• https://github.com/purescript-contrib/purescript-aff-coroutines

Batch 3 [ Completed! ]

Finally, these libraries will take more care and should be left for last:

• https://github.com/purescript-contrib/purescript-aff
• https://github.com/purescript-contrib/purescript-affjax
• https://github.com/purescript-contrib/purescript-react-dom
• https://github.com/purescript-contrib/purescript-react
• https://github.com/purescript-contrib/purescript-parsing
• https://github.com/purescript-contrib/purescript-routing
• https://github.com/purescript-contrib/purescript-css
• https://github.com/purescript-contrib/purescript-matryoshka

[thomashoneyman]

Edit: the checklist has moved:

https://github.com/purescript-contrib/governance/blob/main/updater/UpdateChecklist.md

[JordanMartinez]

@thomashoneyman Minor typo here:

- git mv .github/pull_request_template .github/PULL_REQUEST_TEMPLATE.md
+ git mv .github/pull_request_template.md .github/PULL_REQUEST_TEMPLATE.md

Also, spago init should be spago init -C to remove comments by default.

I need further clarification on how to use the contrib-updater tool correctly in regards to the package name fields:

  --display-name STRING    How to render this library's name in .md files.
                           Default: '`package-name`'
  --title STRING           How to render this library's name in titles. Default:
                           'package-name'

Given I have package purescript-foo, what should display-name and title be? I assume it's this:

contrib-updater generate --display-name purescript-foo --title purescript-foo

However, you said purescript-uri should be URI in some cases. Based on the docs above, it wasn't clear to me when one should be used over the other.

I'll update this with more comments if I come across any.

[JordanMartinez]

I'm claiming purescript-freet and purescript-string-parsers.

[thomashoneyman]

One quick clarification — package names here are referring to the Spago package name, ie. freet (instead of purescript-freet).

Usually, I supply a capitalized version of the package name as the title — “FreeT” or “String Parsers” — and don’t supply a display name at all (I use the default, which is the package name in backticks).

I only use a custom display name for some libraries like Halogen which are normally referred to by their proper name (Halogen) instead of the package name in backticks.

Thanks for catching those typos! Currently on my phone but I’ll come back and update that later.

[JordanMartinez]

Usually, I supply a capitalized version of the package name as the title — “FreeT” or “String Parsers” — and don’t supply a display name at all (I use the default, which is the package name in backticks).

In other words, if the package is purescript-foo-bar-baz, you would use

contrib-updater generate --title "Foo Bar Baz" --maintainer thomashoneyman

To clarify, should we get our PR reviewed and approved by one of us before merging them in? Or just merge it as soon as it's done?

[thomashoneyman]

Yes, that’s what I would typically do. And yes I think they should be approved before merging.

[thomashoneyman]

I've updated to fix the typos and clean up the instructions a little bit.

[JordanMartinez]

Just documenting this:

• The package name used in code snippets (for example, the installation instructions) should be the same as that used in the spago.dhall file (ie. package-name)
• The package name used in README contents should be the same as that used in the spago.dhall file, with backticks (ie. package-name)
• The package name used in README titles should be the same as that used in the spago.dhall file, converted to title case without hyphens (ie. Package Name)
• If a package name needs to be rendered differently in the README files, then you can provide a different format with the --display-title and --display-name flags. For example, the freet library would title case as “Freet” but it really ought to be “FreeT”.

[JordanMartinez]

purescript-these is now done.

[thomashoneyman]

Could I get a review on purescript-contrib/purescript-form-urlencoded#18?

[JordanMartinez]

Ah, sorry about that. I was wondering why you hadn't merged that yet, haha.

[JordanMartinez]

I'll take nullable next.

[JordanMartinez]

Taking purescript-options

[JordanMartinez]

Also taking purescript-http-methods