OISF · jufajardini · Nov 22, 2023 · Nov 22, 2023 · Nov 24, 2023 · Nov 22, 2023
@@ -2,7 +2,7 @@ Contributing to Suricata
 ========================
 
 We're happily taking patches and other contributions. The process is documented at
-[Contribution Process](https://docs.suricata.io/en/latest/devguide/codebase/contributing/contribution-process.html). Please have a look at this document before submitting.
+[Contribution Process](https://docs.suricata.io/en/latest/devguide/contributing/contribution-process.html). Please have a look at this document before submitting.
 
 Contribution Agreement
 ----------------------

@@ -1,7 +1,7 @@
 Make sure these boxes are signed before submitting your Pull Request -- thank you.
 
 - [ ] I have read the contributing guide lines at
-   https://docs.suricata.io/en/latest/devguide/codebase/contributing/contribution-process.html
+   https://docs.suricata.io/en/latest/devguide/contributing/contribution-process.html
 - [ ] I have signed the Open Information Security Foundation contribution agreement at
    https://suricata.io/about/contribution-agreement/ (note: this is only required once)
 - [ ] I have updated the user guide (in doc/userguide/) to reflect the changes made (if applicable)

@@ -13,14 +13,15 @@ developed by the [OISF](https://oisf.net) and the Suricata community.
 - [Home Page](https://suricata.io)
 - [Bug Tracker](https://redmine.openinfosecfoundation.org/projects/suricata)
 - [User Guide](https://docs.suricata.io)
+- [Dev Guide](https://docs.suricata.io/en/latest/devguide/index.html#suricata-developer-guide)
 - [Installation Guide](https://docs.suricata.io/en/latest/install.html)
 - [User Support Forum](https://forum.suricata.io)
 
 ## Contributing
 
 We're happily taking patches and other contributions. Please see our
 [Contribution
-Process](https://docs.suricata.io/en/latest/devguide/codebase/contributing/contribution-process.html)
+Process](https://docs.suricata.io/en/latest/devguide/contributing/contribution-process.html)
 for how to get started.
 
 Suricata is a complex piece of software dealing with mostly untrusted
@@ -105,7 +106,7 @@ change, it will probably go into the next major version.
 __Q: Why was my PR closed?__
 
 A: As documented in the [Suricata GitHub
-workflow](https://docs.suricata.io/en/latest/devguide/codebase/contributing/github-pr-workflow.html),
+workflow](https://docs.suricata.io/en/latest/devguide/contributing/github-pr-workflow.html),
 we expect a new pull request for every change.
 
 Normally, the team (or community) will give feedback on a pull request

@@ -4,7 +4,6 @@ Working with the Codebase
 .. toctree::
    :maxdepth: 2
 
-   contributing/index.rst
    installation-from-git
    code-style
    fuzz-testing

@@ -0,0 +1,107 @@
+========================
+Suricata Backports Guide
+========================
+
+This document describes the processes used to backport content to previous
+Suricata releases. Most often, this means security and/or bug fixes;
+however, in some cases, features may be backported to previous Suricata releases.
+
+There are multiple versions of Suricata at any given time:
+    * Master
+    * Current release
+    * Release prior to current release
+
+For example, at the moment, there are 3 releases based on these Suricata branches:
+    * master: 8.0.0-dev, current development branch
+    * main-7.0.x: current stable release (note we're changing our naming conventions)
+    * master-6.0.x: previous stable release
+
+The next sections discuss when and what to backport, and some guidelines when
+doing so.
+
+What should be backported?
+--------------------------
+
+Usually, when the team creates a ticket, we'll add the *Needs backport* related
+labels, so necessary backporting tickets will be automatically created. If you
+are working on a ticket that doesn't have such labels, nor backporting tasks
+associated, it probably doesn't need backporting. But sometimes we'll miss those.
+
+There can be cases where backports may be "missed" -- some issues may not be
+labeled as needing backports and some PRs may be merged without an issue.
+
+The general principle used to determine what will be backported is:
+    * evasion/security fixes
+    * bug fixes
+    * in some cases, new features are backported if there are sufficient reasons to
+      backport a new feature.
+
+This guide may be insufficient for some situations. When in doubt, please reach
+out to the team on the backport ticket or PR.
+
+Selection overview
+------------------
+
+All items considered for backports should be reviewed with the following:
+    * risk estimate: will the change introduce new bugs? Consider the scope and
+      items affected by the change.
+    * behavioral change: how much will the behavior of the system be changed by the
+      backport. for example, a small change to decode additional encapsulation
+      protocols may result in more traffic being presented to Suricata.
+    * default settings: if the issue alters behavior, can it be made optional, and
+      at what cost?
+
+Creating backport tickets -- new issues
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Redmine: when creating a new redmine issue, label the Redmine issue with "needs
+backport to x.y.z”, where x.y.x is a supported Suricata release, e.g, 7.0.x,
+for security/evasion and bug fixes.
+
+Creating backports tickets -- existing issues/PRs
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+We want to minimize the occurrence of "missed backports" -- that is, work that
+should be backported but wasn't. sometimes this happens when there is no Redmine
+issue, or the redmine issue wasn't labeled as needing a backport.
+
+Therefore, we will be periodically reviewing:
+    * redmine issues without backport labels, including recently closed issues, to
+      see which require backport labels.
+    * prs without associated redmine issues. Those requiring backports should be
+      labeled with *needs backport*.
+
+Then, also periodically, we will create backport issues from those items
+identified in the previous steps. When doing so, we will evaluate what are the
+relevant target backport releases. Some issues reported against master or the
+current Suricata release may not apply to older releases.
+
+Git Backport Workflow
+---------------------
+
+    * *Identify the commit(s) needed* for the backport. Start with the PR that merged
+      the commits into master and select only the commits from the issue being
+      backported.
+    * *Bring each commit into the new branch,* one at a time -- starting with the oldest
+      commit. Use ``git cherry-pick -x commit-hash`` as it maintains the
+      linkage with the cherry-picked commit.
+    * *Resolve conflicts:* Some of the cherry-picked commits may contain merge
+      conflicts. If the conflicts are small, include the corrections in the
+      cherry-picked commit.
+    * *Add additional commits*, if any are needed (e.g., to adjust cherry-picked code
+      to old behavior).
+
+Create a PR:
+~~~~~~~~~~~~
+
+Please indicate in the title that this is a backport PR, with something like
+*(7.0.x-backport)*.
+
+In the PR description, indicate the backport ticket.
+
+QA
+--
+
+Add suricata-verify PRs when needed. Some existing suricata-verify tests may require
+version specification changes.
+
@@ -9,16 +9,18 @@ Commits
 #. Commits need to be logically separated. Don't fix unrelated things in one commit.
 #. Don't add unnecessary commits, if commit 2 fixes commit 1 merge them together (squash)
 #. Commits need to have proper messages, explaining anything that is non-trivial
-#. Commits should not at the same time change, rename and/or move code. Use separate commits
-   for each of this, e.g, a commit to rename files, then a commit to change the code.
-#. Documentation updates should be in their own commit (not mixed with code commits)
-#. Commit messages need to be properly formatted:
-    * Meaningful and short (50 chars max) subject line followed by an empty line
-    * Naming convention: prefix message with sub-system ("rule parsing: fixing foobar"). If
-      you're not sure what to use, look at past commits to the file(s) in your PR.
-    * Description, wrapped at ~72 characters
+#. Commits should not, at the same time, change, rename and/or move code. Use separate commits
+     for each of this, e.g, a commit to rename files, then a commit to change the code.
+#. If your code changes or adds new behavior, update the documentation in the same commit.
+     Otherwise, documentation updates should be in their own commit (not mixed with code commits).
+#. Commit messages need to be properly formatted (check the example further
+     below in this section):
+      * Meaningful and short (50 chars max) subject line followed by an empty line
+      * Naming convention: prefix message with sub-system (**"rule parsing: fixing foobar"**). If
+        you're not sure what to use, look at past commits to the file(s) in your PR.
+      * Description, wrapped at ~72 characters
 #. Commits should be individually compilable, starting with the oldest commit. Make sure that
-   each commit can be built if it and the preceding commits in the PR are used.
+     each commit can be built if it and the preceding commits in the PR are used.
 #. Commits should be authored with the format: "FirstName LastName <name@example.com>"
 
 Information that needs to be part of a commit (if applicable):

@@ -37,10 +37,10 @@ optimizations, and/or ask for help, it is important to communicate.
 
 These are our main channels:
 
-- `Suricata's issue tracker <https://redmine.openinfosecfoundation.org/
+* `Suricata's issue tracker <https://redmine.openinfosecfoundation.org/
   projects/suricata/issues>`_
-- `Suricata's forum <https://forum.suricata.io/c/developers/8>`_
-- `Suricata's Discord server <https://discord.com/invite/t3rV2x7MrG>`_
+* `Suricata's forum <https://forum.suricata.io/c/developers/8>`_
+* `Suricata's Discord server <https://discord.com/invite/t3rV2x7MrG>`_
 
 
 .. _claim-ticket:
@@ -151,18 +151,20 @@ it, so everyone knows that work is still open and waiting to be done.
 What branch to work on
 ======================
 
-There are 2 or 3 active branches:
+There are usually 2 or 3 active branches:
 
-    * master-x.x.x (e.g. master-6.x.y)
+    * master-x.x.x (e.g. master-6.0.x)
+    * main-x.x.x (e.g. main-7.0.x)
     * master
 
-The former is the stable branch. The latter the development branch.
+The ones with version numbers are stable branches. **master** is the development branch.
 
-The stable branch should only be worked on for important bug fixes. Those are
-mainly expected from more experienced contributors.
+The stable branch should only be worked on for important bug fixes or other
+needed :doc:`backports<backports-guide>`. 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
+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

@@ -0,0 +1,65 @@
+GitHub Pull Request Workflow
+============================
+
+Draft Pull Requests
+~~~~~~~~~~~~~~~~~~~
+
+A Pull Request (PR) should be marked as *draft* if it is not intended to be merged as is,
+but is waiting for some sort of feedback.
+The author of the PR should be explicit with what kind of feedback is expected
+(CI/QA run, discussion on the code, etc...)
+
+The GitHub filter is ``is:pr is:open draft:true sort:updated-asc``.
+
+A draft may be closed if it has not been updated in two months.
+
+Mergeable Pull Requests
+~~~~~~~~~~~~~~~~~~~~~~~
+
+When a Pull Request is intended to be merged as is, the workflow is the following:
+ 1. get reviewed, and either request changes or get approved
+ 2. if approved, get staged in a next branch (with other PRs), wait for CI validation
+    (and eventually request changes if CI finds anything)
+ 3. get merged and closed
+
+ Once submitted, we aim at providing a first PR review within two weeks and a
+ month.
+
+ If either code, documentation wording or commit messages need re-work, the
+ reviewer will set the PR state to *changes requested*.
+
+.. note:: It is expected that the author will create a new PR with a new version
+   of the patch as described in :ref:`Pull Requests Criteria <pull-requests-criteria>`.
+   A PR may be closed as stale if it has not been updated in two months after
+   changes were requested.
+
+A PR may be labeled *decision-required* if the reviewer thinks the team needs
+more time to analyze the best approach to a proposed solution or discussion
+raised by the PR.
+
+Once in approved state, the PRs are in the responsibility of the merger, along
+with the next branches/PRs.
+
+Reviewers and Maintainers
+-------------------------
+
+A newly created PR should match the filter::
+
+    is:pr is:open draft:false review:none sort:updated-asc no:assignee
+
+The whole team is responsible to assign a PR to someone precise within 2 weeks.
+
+When someone gets assigned a PR, it should get a review status within 2 weeks:
+either changes requested, approved, or assigned to someone else if more
+expertise is needed.
+
+The GitHub filter for changes-requested PRs is::
+
+    is:pr is:open draft:false sort: updated-asc review:changes-requested
+
+The command to get approved PRs is::
+
+    gh pr list --json number,reviewDecision --search "state:open type:pr -review:none" | jq '.[] | select(.reviewDecision=="")'
+
+An approved PR should match the filter: ``is:open is:pr review:approved``.
+
@@ -7,3 +7,4 @@ Contributing
     contribution-process
     code-submission-process
     github-pr-workflow
+    backports-guide
@@ -5,5 +5,6 @@ Suricata Developer Guide
    :maxdepth: 2
 
    codebase/index.rst
+   contributing/index.rst
    internals/index.rst
    extending/index.rst
@@ -77,7 +77,7 @@ support is done by the core team. If someone wants to help maintain
 and support such a feature, we recommend talking to the core team
 before spending a lot of time on it.
 
-Please see :doc:`devguide/codebase/contributing/contribution-process`
+Please see :doc:`devguide/contributing/contribution-process`
 for more information if you wish to contribute.
 
 Distributions