From e75b551a52f0f426b3bc098318d66ec9c75fc9a1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?louiz=E2=80=99?= Date: Sat, 1 Sep 2018 23:12:39 +0200 Subject: Add the contributing.rst doc in the index --- CONTRIBUTING.rst | 101 ------------------------------------------------ doc/contributing.rst | 106 +++++++++++++++++++++++++++++++++++++++++++++++++++ doc/index.rst | 1 + 3 files changed, 107 insertions(+), 101 deletions(-) delete mode 100644 CONTRIBUTING.rst create mode 100644 doc/contributing.rst diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst deleted file mode 100644 index 502acdc..0000000 --- a/CONTRIBUTING.rst +++ /dev/null @@ -1,101 +0,0 @@ -Contributing to biboumi -======================= - -Biboumi’s main workplace is at https://lab.louiz.org/louiz/biboumi - -The repository is also mirrored on other websites, for example on github, -but that’s mainly for the convenience of users. - -Before doing anything, you can come on the `XMPP chatroom`_ to discuss your -changes, issues or ideas. - - -Bug reports, feature requests ------------------------------ - -To open a bug report, or a feature request, please do so on `our gitlab’s -bug tracker`_. - -If the bug you’re reporting is about a bad behaviour of biboumi when some XMPP -or IRC events occur, please try to reproduce the issue with a biboumi running -in log_level=0, and include the relevant logs in your bug report. - -If the issue you’re reporting may have security implications, please -select the “confidential” flag in your bug report. This includes, but is not limited to: - -- disclosure of private data that was supposed to be encrypted using TLS -- denial of service (crash, infinite loop, etc) that can be caused by any - user - - -Code ----- - -To contribute code, you can do so using git: commit your changes on any -publicly available git repository and communicate us its address. This can -be done with a `gitlab merge request`_, or a `github pull request`_ or just -by sending a message into the `XMPP chatroom`_. - -It is suggested that you use gitlab’s merge requests: this will -automatically run our continuous integration tests. - -It is also recommended to add some unit or end-to-end tests for the proposed -changes. - - -Tests ------ - -There are two test suites for biboumi: - -- unit tests that can be run simply using `make check`. - These tests use the Catch test framework, are written in pure C++ - and they should always succeed, in all possible build configuration. - -- a more complex end-to-end test suite. This test suite is written in python3, - uses a specific IRC server (`charybdis`_), and only tests the most complete - biboumi configuration (when all dependencies are used). To run it, you need - to install various dependencies: refer to fedora’s `Dockerfile.base`_ and - `Dockerfile`_ to see how to install charybdis, slixmpp, botan, a ssl - certificate, etc. - - Once all the dependencies are correctly installed, the tests are run with - - `make e2e` - - To run one or more specific tests, you can do something like this: - - `make biboumi && python3 ../tests/end_to_end self_ping basic_handshake_success` - - This will run two tests, self_ping and basic_handshake_success. - - To write additional tests, you need to add a Scenario - into `the __main__.py file`_. If you have problem running this end-to-end - test suite, or if you struggle with this weird code (that would be - completely normal…), don’t hesitate to ask for help. - - -All these tests automatically run with various configurations, on various -platforms, using gitlab CI. - - -Coding style ------------- -Please try to follow the existing style: - -- Use only spaces, not tabs. -- Curly brackets are on their own lines. -- Use this-> everywhere it’s possible. -- Don’t start class attributes with “m_” or similar. -- Type names are in PascalCase. -- Everything else is in snake_case. - - -.. _our gitlab’s bug tracker: https://lab.louiz.org/louiz/biboumi/issues/new -.. _gitlab merge request: https://lab.louiz.org/louiz/biboumi/merge_requests/new -.. _github pull request: https://github.com/louiz/biboumi/pulls -.. _XMPP chatroom: xmpp:biboumi@muc.poez.io -.. _Dockerfile.base: docker/biboumi-test/fedora/Dockerfile.base -.. _Dockerfile: docker/biboumi-test/fedora/Dockerfile -.. _charybdis: https://github.com/charybdis-ircd/charybdis -.. _the __main__.py file: tests/end_to_end/__main__.py diff --git a/doc/contributing.rst b/doc/contributing.rst new file mode 100644 index 0000000..ee499fc --- /dev/null +++ b/doc/contributing.rst @@ -0,0 +1,106 @@ +####################### +Contributing to biboumi +####################### + +Biboumi’s main workplace is at https://lab.louiz.org/louiz/biboumi + +The repository is also mirrored on other websites, for example on github, +but that’s mainly for the convenience of users. + +Before doing anything, you can come on the `XMPP chatroom`_ to discuss your +changes, issues or ideas. + + +Bug reports, feature requests +----------------------------- + +To open a bug report, or a feature request, please do so on `our gitlab’s +bug tracker`_. + +If the bug you’re reporting is about a bad behaviour of biboumi when some XMPP +or IRC events occur, please try to reproduce the issue with a biboumi running +in log_level=0, and include the relevant logs in your bug report. + +If the issue you’re reporting may have security implications, please +select the “confidential” flag in your bug report. This includes, but is not limited to: + +- disclosure of private data that was supposed to be encrypted using TLS +- denial of service (crash, infinite loop, etc) that can be caused by any + user + + +Code +---- + +To contribute code, you can do so using git: commit your changes on any +publicly available git repository and communicate us its address. This can +be done with a `gitlab merge request`_, or a `github pull request`_ or just +by sending a message into the `XMPP chatroom`_. + +It is suggested that you use gitlab’s merge requests: this will +automatically run our continuous integration tests. + +It is also recommended to add some unit or end-to-end tests for the proposed +changes. + + +Tests +----- + +There are two test suites for biboumi: + +- unit tests that can be run simply using `make check`. + These tests use the Catch test framework, are written in pure C++ + and they should always succeed, in all possible build configuration. + +- a more complex end-to-end test suite. This test suite is written in python3, + uses a specific IRC server (`charybdis`_), and only tests the most complete + biboumi configuration (when all dependencies are used). To run it, you need + to install various dependencies: refer to fedora’s `Dockerfile.base`_ and + `Dockerfile`_ to see how to install charybdis, slixmpp, botan, a ssl + certificate, etc. + + Once all the dependencies are correctly installed, the tests are run with + +.. code-block:: sh + + make e2e + +To run one or more specific tests, you can do something like this: + +.. code-block:: sh + + make biboumi && python3 ../tests/end_to_end self_ping basic_handshake_success + +This will run two tests, self_ping and basic_handshake_success. + +To write additional tests, you need to add a Scenario +into `the __main__.py file`_. If you have problem running this end-to-end +test suite, or if you struggle with this weird code (that would be +completely normal…), don’t hesitate to ask for help. + + +All these tests automatically run with various configurations, on various +platforms, using gitlab CI. + + +Coding style +------------ +Please try to follow the existing style: + +- Use only spaces, not tabs. +- Curly brackets are on their own lines. +- Use this-> everywhere it’s possible. +- Don’t start class attributes with “m_” or similar. +- Type names are in PascalCase. +- Everything else is in snake_case. + + +.. _our gitlab’s bug tracker: https://lab.louiz.org/louiz/biboumi/issues/new +.. _gitlab merge request: https://lab.louiz.org/louiz/biboumi/merge_requests/new +.. _github pull request: https://github.com/louiz/biboumi/pulls +.. _XMPP chatroom: xmpp:biboumi@muc.poez.io +.. _Dockerfile.base: docker/biboumi-test/fedora/Dockerfile.base +.. _Dockerfile: docker/biboumi-test/fedora/Dockerfile +.. _charybdis: https://github.com/charybdis-ircd/charybdis +.. _the __main__.py file: tests/end_to_end/__main__.py diff --git a/doc/index.rst b/doc/index.rst index ca1bf0d..b97c8fd 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -20,3 +20,4 @@ XMPP client as if these channels were XMPP MUCs. install admin user + contributing -- cgit v1.2.3