purescript-contrib / purescript-argonaut-codecs

JSON serialization and deserialization with Argonaut.
MIT License
48 stars 46 forks source link

Update library for purescript-contrib best practices #86

Closed thomashoneyman closed 4 years ago

thomashoneyman commented 4 years ago

This pull request is part of an effort to refresh and standardize the PureScript contributor libraries. Specifically, it:

  1. Uses GitHub Actions via setup-purescript for CI CI previously used a combination of Travis and a package.json file for installing dependencies via NPM. These files consistently get out of date and have to be updated across a large number of libraries. Using setup-purescript allows us to stay on the latest versions of PureScript tooling across the contributor organization and run CI for our libraries without relying on Node. This also allows projects that don't use any NPM dependencies to omit a package.json file altogether -- the standard commands are spago install, spago build, and spago test, and we only need the package.json if there are NPM dependencies or the scripts are more than just those three commands.

  2. Adds a stale.yml file The work to maintain the contributor libraries largely falls to myself and Gary. There's a non-trivial workload doing housekeeping across the fifty-ish projects. This file allows us to automatically notify participants about issues without activity after 90 days so they can ping us, or -- if there is no response for another 21 days -- the issue can be closed automatically.

  3. Updates configuration files used in the project Each contributor project should ideally use the same minimal set of configuration files. This update standardizes the .gitignore and adds a standard .editorconfig. For projects that use the FFI we also have a standard eslintrc.json to lint the FFI files.

  4. Converts the project to use Spago for local development In this case the project already used Spago. But this removes the main / test distinction and uses a single Spago file. That's because the Spago file is only used for local development and has no bearing on the dependencies listed in package-sets. It's OK for it to include the test dependencies as well. There's a longer note at the end of this PR which describes future changes for contributor libraries wrt Spago and Bower.

  5. Updates the README and documentation. This is a first step towards ensuring all contrib libraries have adequate documentation comments, written documentation in a docs directory, and tests (even just usage examples) available in a test directory. In this case the library already had a lengthy tutorial, so that's simply been moved to a standard docs location so the main README remains digestible. For other libraries this will entail either creating minimal documentation or creating a placeholder README file with a call to action to request help writing docs. Either way, users should be able to expect documentation in a docs folder when they use a purescript-contributor library.

  6. Updates issue templates and adds new labels GitHub now has support for multiple issue templates, so I've added a standard 'bug report' and 'change request' pair of issue templates. In addition, I'd like to ensure every purescript-contrib library has a good first issue to label small issues new contributors can take on and a document me label to indicate an issue represents a lack of documentation (which could be added to the docs folder.

  7. Updates the contributing file The CONTRIBUTING file now more directly encourages folks to contribute and gives direction on how they might start. It also includes more in the way of development setup, which both trims down the README file and also helps push more people to read the CONTRIBUTING file (which I've tried to keep short).

This PR is the groundwork for some followup efforts to ensure the contributor libraries are kept up-to-date, publish new versions to Pursuit automatically, are welcoming to new contributors, and have adequate documentation, tests, and usage examples.

This PR leaves the Bower file in place. When the purescript/registry is ready to go and the package format has stabilized we can sweep back through the contributor libraries to remove this file and update to the correct package format.