diff --git a/contributing.md b/contributing.md new file mode 100644 index 0000000..d5811b3 --- /dev/null +++ b/contributing.md @@ -0,0 +1,72 @@ + + +# Contributing to Kaleidoscope + +Firstly, thank you for taking an interesting in contributing! Kaleidoscope is an +open-source project, and welcomes contributions in the form of feature code, +bug reports and fixes, tests, feature suggestions and anything else which may +help to make it better software. + +## Before Starting + +It’s a good idea to [discuss](https://discord.gg/7b6mpF6Qcf) potential +changes with one of the maintainers before starting work. Although efforts are +made to document future development work using the [issue tracker](/issues), it +will not always be up-to-date, and the maintainers may have useful information +to share on plans. + +The worst-case scenario would be for a contributor to spend a large amount of +time producing a PR, only for it to be rejected by the maintainers because it +is not consistent with their plans. A quick conversation before starting work +can save a lot of time. + +If a response is not forthcoming in the [Discord +chatroom](https://discord.gg/7b6mpF6Qcf), contacting one of the project +maintainers directly _but publicly_ may help. Please __do not__ contact the +maintainers privately, as it misses a good opportunity to share knowledge with +a wide audience. Jon Pretty can usually be contacted [on +X](https://x.com/propensive). + +All development work—whether bugfixing or implementing new +features—should have a corresponding issue before work starts. If you +have commit rights to the `propensive/kaleidoscope` repository, push to a branch named +after the issue number, prefixed with `issue/`, for example, `issue/423`. + +## Contribution standards + +Pull requests should try to follow the coding style of existing code in the +repository. They are unlikely to be rejected on grounds of formatting, except +in extreme cases. Kaleidoscope does not use automatic code-formatting because it +has proven to produce unreliable results (and furthermore, hand-formatting is +not particularly laborious). + +Unfortunately an official coding style guide does not yet exist. + +Any code that is inconsistently formatted will be fixed before merging, without +complaint. + +Pull requests should have at least one review before being merged. When opening +a PR, contributors are welcome to suggest a reviewer. Pull requests should be +left in _draft_ mode until they are believed to be ready for review. + +For code contributions, we prefer pull requests with corresponding tests. But +we should not _let perfect be the enemy of the good_. Changes which break +existing tests, however, are likely to be rejected during review. + +## Reporting issues + +New issues are welcome, both as bug reports and feature suggestions. More +detail is preferable, and the clearest and most detailed reports will most +likely be addressed sooner, but a short report from a busy developer is still +preferred over a bug we never hear about. We will ask for more detail in triage +if it’s needed. + +## Conduct + +Contributors and other participants in online discussions are expected to be +polite, on-topic and to nurture a pleasant development environment for all +Kaleidoscope’s users. Propensive OÜ reserves the right to censure +and—in extreme cases—ban users whose behavior, in their opinion, is +detrimental toward this goal. But individualism is valued, and nobody should +feel constrained in how they express themselves. +