25.1.1.2. Code Submission Process

25.1.1.2.1. Commits

  1. Commits need to be logically separated. Don’t fix unrelated things in one commit.
  2. Don’t add unnecessary commits, if commit 2 fixes commit 1 merge them together (squash)
  3. Commits need to have proper messages, explaining anything that is non-trivial
  4. 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.
  5. Documentation updates should be in their own commit (not mixed with code commits)
  6. 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
  7. 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.

Information that needs to be part of a commit (if applicable):

  1. Ticket it fixes. E.g. “Fixes Bug #123.”
  2. Compiler warnings addressed.
  3. Coverity Scan issues addressed.
  4. Static analyzer error it fixes (cppcheck/scan-build/etc)

25.1.1.2.2. Pull Requests

A github pull request is actually just a pointer to a branch in your tree. Github provides a review interface that we use.

  1. A branch can only be used in for an individual PR.
  2. A branch should not be updated after the pull request
  3. A pull request always needs a good description (link to issue tracker if related to a ticket).
  4. Incremental pull requests need to link to the prior iteration
  5. Incremental pull requests need to describe changes since the last PR
  6. Link to the ticket(s) that are addressed to it.
  7. When fixing an issue, update the issue status to In Review after submitting the PR.
  8. Pull requests are automatically tested using github actions (https://github.com/OISF/suricata/blob/master/.github/workflows/builds.yml). Failing builds won’t be considered and should be closed immediately.
  9. Pull requests that change, or add a feature should include a documentation update commit

25.1.1.2.3. Tests and QA

As much as possible, new functionality should be easy to QA.

  1. Add suricata-verify tests for verification. See https://github.com/OISF/suricata-verify
  2. Add unittests if a suricata-verify test isn’t possible.
  3. Provide pcaps that reproduce the problem. Try to trim as much as possible to the pcap includes the minimal set of packets that demonstrate the problem.
  4. Provide example rules if the code added new keywords or new options to existing keywords