diff --git a/doc/userguide/devguide/codebase/code-style.rst b/doc/userguide/devguide/codebase/code-style.rst index 3a604cb38c..16567e5ac8 100644 --- a/doc/userguide/devguide/codebase/code-style.rst +++ b/doc/userguide/devguide/codebase/code-style.rst @@ -1,3 +1,5 @@ +.. _Coding Style: + Coding Style ============ @@ -10,16 +12,13 @@ clang-format ^^^^^^^^^^^^ ``clang-format`` is configured to help you with formatting C code. -.. Argh, github does not support admonitions such as .. note:: +.. note:: -+-------------------------------------------------------+ -| **Note** | -| | -| The ``.clang-format`` file requires clang 9 or newer. | -+-------------------------------------------------------+ + The ``.clang-format`` script requires clang 9 or newer. Format your Changes ******************* + Before opening a pull request, please also try to ensure it is formatted properly. We use ``clang-format`` for this, which has git integration through the ``git-clang-format`` script to only format your changes. @@ -29,19 +28,15 @@ manager). If so, you can simply run it. It is recommended to format each commit as you go. However, you can always reformat your whole branch after the fact. -.. Argh, github does not support admonitions such as .. note:: +.. note:: -+----------------------------------------------------------------------------+ -| **Note** | -| | -| Depending on your installation, you might have to use the version-specific | -| ``git clang-format`` in the commands below, e.g. ``git clang-format-9``, | -| and possibly even provide the ``clang-format`` binary with | -| ``--binary clang-format-9``. | -| | -| As an alternative, you can use the provided ``scripts/clang-format.sh`` | -| that isolates you from the different versions. | -+----------------------------------------------------------------------------+ + Depending on your installation, you might have to use the version-specific + ``git clang-format`` in the commands below, e.g. ``git clang-format-9``, + and possibly even provide the ``clang-format`` binary with + ``--binary clang-format-9``. + + As an alternative, you can use the provided ``scripts/clang-format.sh`` + that isolates you from the different versions. Formatting the most recent commit only """""""""""""""""""""""""""""""""""""" @@ -122,8 +117,6 @@ change. Formatting a whole file """"""""""""""""""""""" -.. Argh, github does not support admonitions such as .. note:: - +--------------------------------------------------------------------+ | **Note** | | | @@ -250,7 +243,7 @@ Functions should have the opening brace on a newline: DoSomething(); } -Note: this is a fairly new requirement, so you'll encounter a lot of non-compliant code. +Note: you may encounter non-compliant code. Control and loop statements should have the opening brace on the same line: @@ -752,4 +745,4 @@ Example: https://github.com/oisf/suricata/blob/master/src/decode-ethernet.c .. [clang9] Requires clang 9 .. [clang10] Requires clang 10 .. [clang11] Requires clang 11 -.. [breakbeforebraces] BreakBeforeBraces: Mozilla is closest, but does not split empty functions/structs \ No newline at end of file +.. [breakbeforebraces] BreakBeforeBraces: Mozilla is closest, but does not split empty functions/structs diff --git a/doc/userguide/devguide/codebase/contributing/code-submission-process.rst b/doc/userguide/devguide/codebase/contributing/code-submission-process.rst index 87aeb2397a..129f124065 100644 --- a/doc/userguide/devguide/codebase/contributing/code-submission-process.rst +++ b/doc/userguide/devguide/codebase/contributing/code-submission-process.rst @@ -1,6 +1,8 @@ Code Submission Process ======================= +.. _commits: + Commits ~~~~~~~ @@ -25,6 +27,8 @@ Information that needs to be part of a commit (if applicable): #. Coverity Scan issues addressed. #. Static analyzer error it fixes (cppcheck/scan-build/etc) +.. _pull-requests-criteria: + Pull Requests ~~~~~~~~~~~~~ diff --git a/doc/userguide/devguide/codebase/contributing/contribution-process.rst b/doc/userguide/devguide/codebase/contributing/contribution-process.rst new file mode 100644 index 0000000000..dcbc86557f --- /dev/null +++ b/doc/userguide/devguide/codebase/contributing/contribution-process.rst @@ -0,0 +1,257 @@ +************************ +Contributing to Suricata +************************ + +This guide describes what steps to take if you want to contribute a patch or +patchset to Suricata. + +Essentially, these are: + +#. Agree to and sign our :ref:`Contribution Agreement` +#. Communicate early, and use the :ref:`preferred channels ` +#. :ref:`claim-ticket` +#. :ref:`Fork from master ` +#. Follow our :ref:`Coding Style` +#. Use our :ref:`documentation-style` +#. Stick to our :ref:`commit guidelines` +#. Add version numbers to your :ref:`Pull Requests ` +#. Incorporate :ref:`feedback` into new PRs +#. [Work merged] :ref:`Wrap up! ` + +The rest of this document will cover those in detail. + +.. _contribution-agreement: + +.. note:: Important! + + Before contributing, please review and sign our `Contribution Agreement + `_. + +.. _communication-channels: + +Communication is Key! +===================== + +To clarify questions, discuss or suggest new features, talk about bugs and +optimizations, and/or ask for help, it is important to communicate. + +These are our main channels: + +- `Suricata's issue tracker `_ +- `Suricata's forum `_ +- `Suricata's Discord server `_ + + +.. _claim-ticket: + +Claim (or open) a ticket +======================== + +For features and bugs we need `tickets `_. Tickets help us keep track of the work done, +indicate when changes need backports etc. + +They are also important if you would like to see your new feature officially +added to our tool: the ticket documents your ideas so we can analyze how do they +fit in our plans for Suricata, and, if the feature is accepted, we can properly +track progress etc. + +.. note:: If you want to add new functionalities (e.g. a new application layer + protocol), please ask us first whether we see that being merged into + Suricata or not. This helps both sides understand how the new feature will + fit in our roadmap, and prevents wasting time and motivation with + contributions that we may not accept. Therefore, `before` starting any code + related to a new feature, do request comments from the team about it. + +For really trivial fixes or cleanups we won't need that. + +Once work on the issue has been agreed upon: + +Assign the ticket to yourself. For this, you will need to have the "developer" +role. You can ask for that directly on the ticket you want to claim or mention +that you are interested in working on `ticket number` on our `Developer's +channel on Discord `_. + +If a ticket is already assigned to someone, please reach out on the ticket or +ask the person first. + +You can reach out to other community members via `Suricata's Discord server +`_. + + +Expectations +============ + +If you submit a new feature that is not part of Suricata's core functionalities, +it will have the `community supported`_ status. This means we would expect some +commitment from you, or the organization who is sponsoring your work, before we +could approve the new feature, as the Suricata development team is pretty lean +(and many times overworked). + +This means we expect that: + + * the new contribution comes with a set of Suricata-verify tests (and + possibly unit tests, where those apply), before we can approve it; + * proof of compatibility with existing keywords/features is provided, + when the contribution is for replacing an existing feature; + * you would maintain the feature once it is approved - or some other + community member would do that, in case you cannot. + +.. note:: + + Regardless of contribution size or complexity, we expect that you respect + our guidelines and processes. We appreciate community contributors: + Suricata wouldn't be what it is without them; and the value of our tool and + community also comes from how seriously we take all this, so we ask that + our contributors do the same! + +.. _community supported: + +What does "community supported" and "supporting a feature" mean? +----------------------------------------------------------------- + +If a feature is *community supported*, the Suricata team will try to spend +minimal time on it - to be able to focus on the core functionalities. If for any +reason you're not willing or able to commit to supporting a feature, please +indicate this. + +The team and/or community members can then consider offering help. It is best +to indicate this prior to doing the actual work, because we will reject features +if no one steps up. + +It is also important to note that *community supported* features will be +disabled by default, and if it brings in new dependencies (libraries or Rust +crates) those will also be optional and disabled by default. + +**Supporting a feature** means to actually *maintain* it: + +* fixing bugs +* writing documentation +* keeping it up to date +* offering end-user support via forum and/or Discord chat + +.. _what-branch-to-work-on: + +What branch to work on +====================== + +There are 2 or 3 active branches: + + * master-x.x.x (e.g. master-6.x.y) + * master + +The former is the stable branch. The latter the development branch. + +The stable branch should only be worked on for important bug fixes. Those are +mainly expected from more experienced contributors. + +Development of new features or large scale redesign is done in the development +branch. New development and new contributors should work with ``master`` except +in very special cases - which should and would be discussed with us first. + +If in doubt, please reach out to us via :ref:`Redmine, Discord or +forum `. + +.. _create-your-own-branch: + +Create your own branch +====================== + +It's useful to create descriptive branch names. You're working on ticket 123 to +improve GeoIP? Name your branch "geoip-feature-123-v1". The "-v1" addition is +for feedback. When incorporating feedback you will have to create a new branch +for each pull request. So, when you address the first feedback, you will work in +"geoip-feature-123-v2" and so on. + +For more details check: `Creating a branch to do your changes `_ + + +Coding Style +============ + +We have a :ref:`Coding Style` that must be followed. + +.. _documentation-style: + +Documentation Style +=================== + +For documenting *code*, please follow Rust documentation and/or Doxygen +guidelines, according to what your contribution is using (Rust or C). + +If you are writing or updating *documentation pages*, please: + +* wrap up lines at 79 (80 at most) characters; +* when adding diagrams or images, we prefer alternatives that can be generated + automatically, if possible; +* bear in mind that our documentation is published on `Read the Docs `_ and can also be + built to pdf, so it is important that it looks good in such formats. + + +Commit History matters +====================== + +Please consider our :ref:`Commit guidelines ` before submitting your PR. + +.. _send-a-pull-request: + +Send a Pull Request +=================== + +The pull request is used to request inclusion of your patches into the main +repository. Before it is merged, it will be reviewed and pushed through a QA +process. + +Please consider our :ref:`Pull Requests Criteria ` when +submitting. + +We have 'GitHub-CI' integration enabled. This means some automated build check, +suricata-verity and unit tests are performed on the pull request. Generally, +this is ready after a few minutes. If the test fails, the pull request won't be +considered. So please, when you submit something, keep an eye on the checks, +and address any failures - if you do not understand what they are, it is fine to +ask about them on the failing PR itself. + +Before merge, we also perform other integration tests in our private QA-lab. If +those fail, we may request further changes, even if the GitHub-CI has passed. + +.. _feedback: + +Feedback +======== + +You'll likely get some feedback. Even our most experienced devs do, so don't +feel bad about it. + +After discussing what needs to be changed (usually on the PR itself), it's time +to go back to ":ref:`create-your-own-branch`" and do it all again. This process +can iterate quite a few times, as the contribution is refined. + +.. _wrap-up: + +Wrapping up +=========== + +Merged! Cleanup +--------------- + +Congrats! Your change has been merged into the main repository. Many thanks! + +We strongly suggest cleaning up: delete your related branches, both locally and +on GitHub - this helps you in keeping things organized when you want to make new +contributions. + +.. _update-ticket: + +Update ticket +------------- + +You can now put the URL of the *merged* pull request in the Redmine ticket. +Next, mark the ticket as "Closed" or "Resolved". + +Well done! You are all set now. diff --git a/doc/userguide/devguide/codebase/contributing/index.rst b/doc/userguide/devguide/codebase/contributing/index.rst index 1338054eab..4c9089e484 100644 --- a/doc/userguide/devguide/codebase/contributing/index.rst +++ b/doc/userguide/devguide/codebase/contributing/index.rst @@ -2,6 +2,7 @@ Contributing ============ .. toctree:: - :maxdepth: 2 + :maxdepth: 2 - code-submission-process + contribution-process + code-submission-process