Contributing

January 1, 2026 ยท View on GitHub

Contribution is encouraged: bug reports, feature requests, or code contributions. New features should be proposed and discussed in an issue.

Before contributing patches, please read the Licence.

This plugin is governed under the Contributor Covenant Code of Conduct.

Code Guidelines

I have several guidelines to contributing code through pull requests:

  • If tests exist for the project, the test suite should pass. New or changed functionality should have tests added. The test suite is written with fishtape.

  • Code style is mostly provided by fish_indent. There are a few things not covered by fish_indent:

    • Where possible, prefer using fish built-ins over external programs like sed or awk.

    • For simple conditional execution, prefer and or or. Avoid chaining these conditions and prefer if with && or || expressions as appropriate.

  • Proposed changes should be on a thoughtfully-named topic branch and organized into logical commit chunks as appropriate.

  • Use Conventional Commits with my conventions.

  • Do not change the version number; when your patch is accepted and a release is made, the version will be updated at that point.

  • Documentation should be added or updated as appropriate for new or updated functionality.

  • All GitHub Actions checks marked as required must pass before a pull request may be accepted and merged.

  • Add your name or GitHub handle to CONTRIBUTORS.md and a record in the CHANGELOG.md as a separate commit from your main change. (Follow the style in the CHANGELOG.md and provide a link to your PR.)

  • Include your DCO sign-off in each commit message (see LICENCE).

AI Contribution Policy

It is extremely important that contributions of any sort be well understood by the submitter and that the developer can attest to the Developer Certificate of Origin for each pull request (see LICENCE).

Any contribution (bug, feature request, or pull request) that uses undeclared AI output will be rejected.

Commit Conventions

This plugin has adopted a variation of the Conventional Commits format for commit messages. The following types are permitted:

TypePurpose
featA new feature
fixA bug fix
choreA code change that is neither a bug fix nor a feature
docsDocumentation updates
depsDependency updates, including GitHub Actions.

I encourage the use of Tim Pope's or Chris Beam's guidelines on the writing of commit messages

I require the use of git trailers for specific additional metadata and strongly encourage it for others. The conditionally required metadata trailers are:

  • Breaking-Change: if the change is a breaking change. Do not use the shorthand form (feat!(scope)) or BREAKING CHANGE.

  • Signed-off-by: this is required for all developers except me, as outlined in the Licence.

  • Fixes or Resolves: If a change fixes one or more open issues, that issue must be included in the Fixes or Resolves trailer. Multiple issues should be listed comma separated in the same trailer: Fixes: #1, #5, #7, but may appear in separate trailers. While both Fixes and Resolves are synonyms, only one should be used in a given commit or pull request.

  • Related to: If a change does not fix an issue, those issue references should be included in this trailer.