Skip to content

CONTRIBUTING

Contributions are welcome. Satty is not able to evolve without relying on its contributors and their contributions.

We're always looking for and are grateful about help with e.g. documentation/README, PRs, PR reviews, FAQ or other wiki entries.

This documents tries to reduce friction when it comes to contributions by defining some guidelines, some of which may follow a rationale while others are arbitrary determinations.

Please note that opening a PR or even just an issue may expose your work to pertinent discussion regarding code quality, Satty's scope and these guidelines, and possibly things we haven't yet thought of. This isn't meant as discouragement, just as a heads-up.

Issues for bugs or feature requests

Bug reports and ideas for Satty are valuable contributions. But please take the time to search for existing issues.

Issue first, then PR

The issue should state what is missing from or broken in Satty. All the discussion around whether a feature is in scope, or a behaviour is a bug can take place there. A related PR is then just about correctness of a fix or feature implementation. This ensures that a specific feature or fix is actually wanted.

Commits and PRs

  • We may squash commits in a PR for easier reverting and to avoid commits that are scattered along the change log.
  • If github indicates conflicts, please rebase your branch instead of merging upstream changes. We know that having to rebase sucks, so we're doing our best to point out where conflicts may arise even in advance, but sometimes conflicts are inevitable. We're happy to assist with rebasing, just say the word.
  • Please make sure that all commits in a non-draft PR compile.
  • The PR should use a conventional commit message.
  • PRs should not break existing config or disrupt existing user workflows. But if there are potential surprises, please add a "!" for attention, e.g. "fix!", "feat!", and provide a small section that may be included in the release notes.
  • Please fill out the check list provided in our pull request template.

Milestones

We use these to indicate which issues and/or PRs we'd ideally like to include with the next release. This doesn't mean any pressure, or that there's any deadline.

3rd party crates

We would like to keep 3rd party dependencies to a minimum. Addition of new dependencies should only be considered if - the relevant code parts are non-trivial - the functionality in question cannot be provided via existing dependencies

Additionally, replacement of dependencies with a different dependency is possible, e.g. if - the old dependency became unmaintained - the new dependency is superior in a way that is relevant to Satty - the new dependency has advantages for future cross-platform compatibilty

Code comments

Ideally, code should be written in a way that it is self-explanatory. Comments can always help make code parts more understandable. They especially make sense when a section - was tricky to figure out - is sophisticated or unintuitive or not immediately obvious - might be in jeooardy of being overwritten by future you or other contributors due to not understanding it properly later

Please note that we may also ask for additional comments on the back of PRs.

Code formatting and hints/improvements

Please use cargo fmt to apply formatting and cargo clippy to fix all suggestions pertinent to your changes. You can use make fix for both. Please note that this may apply changes unrelated to your code: - formatting if previous commits have not used cargo fmt - hints if previous commits have not used cargo clippy OR clippy is newer than the last commit and has learned new hints in the meantime

Missing formatting/hints that precede your PR should be addressed via a separate issue/PR in main branch first. If in doubt how to resolve such a situation, ask.

README changes

If a PR changes Satty's behaviour and where appropriate, please adjust README.md/documentation as well. make update-usage adds the command line help (output of satty --help) as well as the example config.toml automatically which is relevant whenever command line arguments or config change. While it can be tempting to add other fixes to the README while you're at it, unrelated changes to it which precede your PR should be addressed in a separate issue/PR first. If in doubt how to resolve such a situation, ask.

Command line parameters changes

Please include anticipated next version in the comment for command line arguments, especially when adding arguments or options. You can use the placeholder NEXTRELEASE in command_line.rs, configuration.rs and README.md.

LLM/Generative AI usage

Please refer to our AI POLICY.