diff --git a/docs/contributing.rst b/docs/contributing.rst new file mode 100644 index 0000000..ceeb29a --- /dev/null +++ b/docs/contributing.rst @@ -0,0 +1,74 @@ +Contributing +============ + +The pull requests, bug reports, feature suggestions or even demo use cases contributed by the pyircbot community are all +highly appreciated and a valuable asset to the project. + +This document outlines best practices and conditions for contributing changes pyircbot. + + +Sending a Pull Request +---------------------- + +The pyircbot project does have a couple rules for pull requests: + + +Where + While pyircbot's main git repository is hosted on a private server, PRs are welcome on the + `github mirror `_ of the project. + + +Linting + Pyircbot's codebase is linted with flake8. The configuration arguments for flake8 are: ``--max-line-length 120 + --ignore E402,E712,E731,E211 --select E,F``. TODO add a flake8 config file to the repo so these args are codified. + + +Python versions + Pyircbot supports the two latest versions of python 3. At present, this is Python 3.6 and 3.7. All changes must be + compatible with these versions. Using compatibility modules or checking the version at runtime is discouraged; the + code should be written in a fashion that is interoperable. + + +Dependencies + The core of pyircbot - that is, the bot runtime itself and the basic modules needed to operate it - `PingResponder` + and `Services` - have no dependencies outside python's standard library of modules. All changes must not change this + condition. The use of 3rd party dependencies in pyircbot modules is allowed, provided the versions used do not + conflict with modules already in use. + + All 3rd party dependencies must be installable via Pip with no extra setup required (e.g. OS-level packages), with + some exceptions: + + - Requiring ``git`` for pip links directly to repositories is permitted. + + - Requiring a C/C++ compiler available on the system as well as python headers which are typically required for + libraries with C/C++ or other native language extensions is permitted. However, requiring additional headers or + shared libraries is prohibited, unless: + + - Many operating systems provide a ``python3-pip`` or similar package that depends on many other packages that violate + the above rules, such as openssl headers or sqlite shared libraries. Pyircbot's preferred platform is Ubuntu Bionic, + and any dependencies of such a package are permitted. + + - These rules apply to code dependencies only, and do not apply to external *services* such as MySQL. + + Modules that require setup or dependencies beyond these rules will not be accepted into the core module set. The + recommended approach to use such a module is via the ``usermodules`` config directive. + + No set of rules will handle all cases, and discussion or defending a change that violates these rules is encouraged. + + +Tests + Please consider the test suite when submitting changes affecting the core runtime and existing modules. Reduction of + coverage is acceptable, but breaking or removing tests is not. Changes submitted with updated or new tests will + be fast-tracked. + + +Contributors to Pyircbot +------------------------ + +Any change submitted to pyircbot is highly appreciated. + +Our contributors, in no particular order: + +- `@ollien `_ ❤️ +- `@medmr1 `_ ❤️ +- `@dpedu `_ ❤️ diff --git a/docs/index.rst b/docs/index.rst index 83a3800..6a40210 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -15,6 +15,7 @@ Contents: module_guide/_module_guide.rst module_guide/_pubsub_mode.rst changelog.rst + contributing.rst More Information ================