purescript-contrib / governance

Guidelines and resources for the PureScript Contributors organization
15 stars 3 forks source link

Introduce `contrib-updater` CLI tool for maintenance tasks #3

Closed thomashoneyman closed 4 years ago

thomashoneyman commented 4 years ago

One of the biggest headaches of maintaining Contributor libraries is having to apply some update across all the repositories -- which often requires manually stepping through the whole list updating package.json files or copying in new files or whatever the task may be. It also tends to be quite error-prone.

This PR introduces a Swiss Army knife CLI tool for performing maintenance tasks. At the moment, all this does is allow us to generate the standard files outlined in the Library Guidelines for a library, but this is already a step above manually copying files around.

The README contains instructions on installing this CLI tool on your system via npm link. It can then be used, for example, like this:

contrib-updater generate --uses-js --maintainer garyb --displayTitle 'Codec Argonaut'

The tool is just a first step. It can easily be extended over time to help automate other Contributor-related tasks. The core of the application is the Command type and associated run function:

-- | The data type which describes what tasks this CLI tool can assist with. See
-- | the library documentation for a full description of what these commands are
-- | intended to accomplish.
data Command
  = Generate GenerateOptions

-- | Run a command, performing any relevant updates (for example, on the filesystem or over the GitHub API)
run :: Command -> Effect Unit
run = launchAff_ <<< case _ of
  Generate opts ->
    runGenerate opts

This can be extended over time to accommodate other commands. For example, if we added a command to ensure that issue labels are kept in sync across the organization, then we would expand the Command type to include this constructor, expand the Cli.purs module to parse the arguments appropriately, and then add the implementation to the run function.

There is a whole lot more we could do with this over time (for example, we could be a lot smarter about the templates), but this feels like an adequate first step. Closes #1.

milesfrain commented 4 years ago

Looks good overall, but I think I'd have more feedback to give if I was using this myself to update libs.

thomashoneyman commented 4 years ago

I've been sticking to 'variables only replace the key with the value the user provides', which means that using the maintainer key to create badges only works if there's one. For the time being I think I'm going to keep it that way for simplicity and manually add other maintainers by editing the file -- but I agree that really this ought to support multiple maintainers by default.

I don't want you to have to dig into the source code to see what will happen to the variable you provided in the template when it is replaced -- it's nice knowing that you'll only get a simple string replacement.