Skip to content

Adding a Restyler

Jump to bottom
Pat Brisbin edited this page Aug 5, 2024 · 42 revisions

Restylers can be added by anyone through a Pull Request on the restylers repository. There is no burden of popularity or usefulness. Most Restylers can even be configured to run by default, provided they don't conflict with other Restylers that operate on the same file-types.

✋ If the Restyler you're planning to add is just a modified version of an existing one, don't follow these instructions. Instead, you can do something simpler, called an override Restyler. See prettier-markdown and prettier-yaml as examples that override the prettier Restyler.

Prerequisites

  1. git
  2. Docker
  3. A Haskell tool-chain

To get started, check out the restyled-io/restylers, repository:

git clone https://github.com/restyled-io/restylers
cd restylers

0. The Auto-formatter

For this tutorial, we will fabricate our own simple auto-formatter to wrap:

#!/bin/sh
for path; do
  sed -i 's/apple/banana/g' "$path"
done

Place this script at ./bananas/files/usr/bin/bananas, and make it executable.

1. Create the Restyler

You need only two files, described below.

./bananas/info.yaml:

name: bananas
version_cmd: |
  echo "v0.0.1"
include:
  - "**/*"
supports_arg_sep: false
metadata:
  languages:
    - Any
  tests:
    - contents: |
        Hi, here are some apples.
      restyled: |
        Hi, here are some bananas.

See here for documentation on this file.

✔️ It's very important to add tests. Since I'm not always familiar with the language, conventions, or other aspects of the auto-formatters we run, we need to have these assertions that it's working as intended when you add it and as it's maintained and upgraded over time.

./bananas/Dockerfile:

FROM alpine:3.10.3
LABEL maintainer="You <[email protected]>"
RUN mkdir -p /code
WORKDIR /code
COPY files /
CMD ["bananas"]

2. Test locally

Build the Docker image and run the tests:

./bin/test bananas

NOTE: if this doesn't work, and you can't make it work, please still submit the PR and we'll help you out through its review.

That's it! Open a Pull Request and we'll go from there.

When will you see your changes?

When your change lands in main, we will promote them to the dev channel. This should make it easy for you to use yourself and impact any other users who run dev. See here for how channels work generally.

On the 1st and 15th of every month, dev is promoted to stable, releasing your changes to our entire user base.

Examples

The following are Restylers that wrap tools in certain languages. They can be good examples if you are trying to build a Restyler for a tool that is built or installed similarly.

Removed

Clone this wiki locally