diff --git a/doc/userguide/devguide/contributing/backports-guide.rst b/doc/userguide/devguide/contributing/backports-guide.rst new file mode 100644 index 000000000000..42459ba0ed92 --- /dev/null +++ b/doc/userguide/devguide/contributing/backports-guide.rst @@ -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. + diff --git a/doc/userguide/devguide/contributing/index.rst b/doc/userguide/devguide/contributing/index.rst index e0d29125bbdd..9b1baeaab139 100644 --- a/doc/userguide/devguide/contributing/index.rst +++ b/doc/userguide/devguide/contributing/index.rst @@ -7,3 +7,4 @@ Contributing contribution-process code-submission-process github-pr-workflow + backports-guide