Thanks for contributing to trunk's default plugins! Read on to learn more.
We use this repository to provide our users with default linters, actions, and tools. Trunk automatically adds the following to users' trunk.yaml:
plugins:
sources:
- id: trunk
uri: https://github.com/trunk-io/plugins
ref: <latest_release>
Plugins can also be loaded from local paths, as below:
plugins:
sources:
- id: trunk
local: </path/to/repo/root>
Adding a plugin source lets users run trunk check enable
or trunk actions enable
with linters
and actions defined in that plugin. For more information, see our
docs.
If you have questions, please stop by our community Slack, and if you have a feature request, you can file it here.
trunk-io/plugins
is released on a fairly regular cadence that is independent of PRs. Users will
pick up these configuration changes by running trunk upgrade
to automatically update their plugin
version to the latest release.
plugins:
sources:
- id: trunk
uri: https://github.com/trunk-io/plugins
ref: v1.2.5 # will change to the latest release on next `trunk upgrade`
We recommend only setting the above ref
field to be our released tags, but if you need a linter or
action that hasn't been released yet, you can set ref
to be a git SHA. Do not set ref
to be
a branch name, or HEAD
, as users will observe buggy behavior.
Note that the ref and the cli version in the trunk.yaml must be compatible. This is managed by
required_trunk_version
, as specified in plugin.yaml
. Users will not be able to
load a plugin source until they have upgraded to a compliant CLI version.
To add a new linter:
-
Run
trunk check
to start up Trunk in the background. -
Create a directory inside
linters/
with the name of your new linter. -
Inside this new directory, create the following structure. Most of these files will be automatically created for you:
linters/ └─my-linter/ │ plugin.yaml │ my_linter.test.ts │ README.md (optional) │ my-config.json (optional) └─test_data/ └─basic.in.py (with appropriate extension)
-
Add your linter definition to
plugin.yaml
(consult the docs for custom linters and custom parsers to understand how it should be defined). Most linters in this repository are defined as tools as well, so that they can be easily run manually from the command line. -
Making sure the plugin in
.trunk/trunk.yaml
is pointing to your local repository, runtrunk check enable <my-linter>
to enable your linter, and runtrunk check
to verify that the configuration is valid and that you get desired diagnostics. Runningtrunk check --verbose
can help provide greater insights when debugging. -
Add a few simple test cases to
my_linter.test.ts
to exercise your linter and generate snapshots. Refer to Testing Guidelines for more information on writing and running tests. -
Run
trunk check
to lint your changes. -
Open a PR!
To add a new action:
-
Create a directory inside
actions/
with the name of your new action. -
Inside this new directory, create the following structure:
actions/ └─my-action/ │ plugin.yaml └─README.md
-
Add your action definition to
plugin.yaml
(consult the docs on actions to understand how it should be defined). -
If necessary, add additional scripts in the same directory for your action to reference.
-
Making sure the plugin in .trunk/trunk.yaml is pointing to your local repository, run
trunk actions enable <my-action>
to enable your linter, and runtrunk run <my-action>
to verify that the configuration is valid and that you get desired results. Runningtrunk actions history <my-action>
can help provide greater insights when debugging. -
We have not yet defined a testing framework for plugin actions, but we are working to add one soon! Please briefly document your action in its README.md and in your PR.
-
Run
trunk check
to lint your changes. -
Open a PR!
If the tool you intend to add functions primarily as a linter, please follow the instruction in
linters. If it functions more as a standalone tool, please add it in the tools/
directory and follow the instructions below.
To add a new tool:
-
Run
trunk check
to start up Trunk in the background. -
Create a directory inside
tools/
with the name of your new linter. -
Inside this new directory, create the following structure. Most of these files will be automatically created for you:
tests/ └─my-tool/ │ plugin.yaml │ my_tool.test.ts └─README.md (optional)
-
Add your tool definition to
plugin.yaml
(consult the docs for custom tools to understand how it should be defined). -
Making sure the plugin in
.trunk/trunk.yaml
is pointing to your local repository, runtrunk tools enable <my-tool>
to enable your tool, and access its shim(s) to run it from.trunk/tools/<tool-name>
. -
Add a
toolInstallTest
tomy_tool.test.ts
to verify your tool's installation. If neccessary, usetoolTest
instead. Refer to Testing Guidelines for more information on writing and running tests. -
Run
trunk check
to lint your changes. -
Open a PR!
Please follow the guidelines below when contributing:
- After defining a new linter or action, please add it to
README.md
. - If you run into any problems while defining new linters or actions, feel free to reach out on our Slack. We are continuously working to improve the process of integrating with trunk, and all feedback is appreciated!
For ease of development, we provide support for Github Codespaces.
Just check out the repo in a codespace and you'll have everything ready to go!