Updating contribution guidelines

.config/ci/check_commits.sh

@@ -0,0 +1,33 @@
+#!/bin/bash
+
+# SPDX-License-Identifier: GPL-2.0-only
+
+# Check all commits in the PR have the "AI-Assisted" tag
+# We copy Wireshark's contributing guide, thanks to them for the idea !
+# This script is inspired by https://gitlab.com/wireshark/wireshark/-/blob/master/.gitlab-ci.yml
+
+commits=$(git rev-list --no-merges --max-count=$((PR_FETCH_DEPTH - 1)) HEAD)
+if [ -z "$commits" ]; then
+    echo "No commit to check in PR. OK."
+    exit 0
+fi
+
+missing=0
+for c in $commits; do
+    if ! git log -1 --format=%B "$c" | grep -qi '^AI-Assisted:'; then
+        echo -e "ERROR: Commit \033[0;33m$c\033[0m is missing the 'AI-Assisted: yes|no [tool(s)]' trailer."
+        missing=1
+    else
+        echo -e "OK: Commit \033[0;32m$c\033[0m is properly tagged."
+    fi
+done
+
+if [ $missing -eq 1 ]; then
+    echo
+    echo -e "\033[0;31mPlease add the 'AI-Assisted' trailer to commit messages !\033[0m"
+    echo "See the contribution guide at: https://github.com/secdev/scapy/blob/master/CONTRIBUTING.md"
+    exit 1
+else
+    echo "All checked commits include the AI-Assisted trailer."
+    exit 0
+fi

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,24 +1,25 @@
-<!-- This is a checklist of actions required to have a PR reviewed. You should include it and fill it accordingly. (You may only remove it if you check all items and you are a well-known contributor.) -->
+<!-- Hi there ! First of all thanks a lot for contributing to Scapy ! We're really grateful for contributions and for the time people spend contributing back. Please note that due to the amount of contributions, we have to impose quality standards for PRs.
 
-**Checklist :**
+Here is a small checklist of actions to get you started with this PR. You may remove this entire section once you're done. Please note that if you don't follow the guidelines detailed here, we might end up closing the PR :( When in doubt, ask !
 
--   [ ] If you are new to Scapy: I have checked [CONTRIBUTING.md](https://github.com/secdev/scapy/blob/master/CONTRIBUTING.md) (esp. section submitting-pull-requests)
--   [ ] I squashed commits belonging together
--   [ ] I added unit tests or explained why they are not relevant
--   [ ] I executed the regression tests (using `tox`)
--   [ ] If the PR is still not finished, please create a [Draft Pull Request](https://github.blog/2019-02-14-introducing-draft-pull-requests/)
--   [ ] This PR uses (partially) AI-generated code. If so:
-    - [ ] I ensured the generated code follows the internal concepts of scapy
-    - [ ] This PR has a test coverage > 90%
-    - [ ] I reviewed every generated line
-    - [ ] If this PR contains more than 500 lines of code (excluding unit tests) I considered splitting this PR.
-     - [ ] I considered interoperability tests with existing packages or utilities to ensure conformity of a newly generated protocol
+Checklist :
 
-**I understand that failing to mention the use of AI may result in a ban. (We do not forbid it, but you must play fair. Be warned !)**
+- Check the contribution guide at https://github.com/secdev/scapy/blob/master/CONTRIBUTING.md (esp. section submitting-pull-requests)
+- Have good commit hygiene. They must have the `AI-Assisted` tag as explained in the contributing guide. Please squash commits that belong together, and split commits that contain multiple features.
+- AI: You must make sure that you understood the internal concepts of Scapy and have good test coverage (like >90%). Please review ALL the code you generated.
+- Add unit tests or explain why they are not relevant.
+- If the PR is still not finished, please create a **Draft Pull Request**
+- If this PR contains more than 500 lines of code (excluding unit tests), consider splitting it.
+- New protocols: I considered interoperability tests with existing packages or utilities to ensure conformity of a newly generated protocol
+
+Please read the output of the tests if they fail ! In rare cases, some tests might fail for reasons unrelated to your PR, sorry about that ! Just explain it and we'll relaunch them.
+-->
+
+### Description
 
 <!-- brief description what this PR will do, e.g. fixes broken dissection of XXX -->
 
-<!-- if required - short explanation why you fixed something in a way that may look more complicated as it actually is ->>
+<!-- if required - short explanation why you fixed something in a way that may look more complicated as it actually is -->
 
 <!-- if required - outline impacts on other parts of the library -->
 

.github/workflows/unittests.yml

@@ -16,14 +16,38 @@ permissions:
   contents: read
 
 jobs:
+  commit:
+    name: Check the validity of the commits
+    runs-on: ubuntu-latest
+    if: github.event_name == 'pull_request'
+    # We follow the same contributing patterns as Wireshark. Thanks to
+    # https://gitlab.com/wireshark/wireshark/-/blob/master/.gitlab-ci.yml
+    steps:
+      - name: Get the number of commits in the PR
+        run: echo "PR_FETCH_DEPTH=$(( ${{ github.event.pull_request.commits }} + 1 ))" >> "${GITHUB_ENV}"
+      - name: Checkout Scapy
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: ${{ env.PR_FETCH_DEPTH }}
+      - name: AI trailer reminder
+        run: bash ./.config/ci/check_commits.sh
+  spdx:
+    name: Check SPDX identifiers (Licensing)
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Scapy
+        uses: actions/checkout@v6
+      - name: Launch script
+        run: bash scapy/tools/check_spdx.sh
   health:
     name: Code health check
     runs-on: ubuntu-latest
+    needs: [commit, spdx]
     steps:
       - name: Checkout Scapy
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
       - name: Setup Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: "3.12"
       - name: Install tox
@@ -39,34 +63,28 @@ jobs:
   docs:
     # 'runs-on' and 'python-version' should match the ones defined in .readthedocs.yml
     name: Build doc
-    runs-on: ubuntu-22.04
+    runs-on: ubuntu-24.04
+    needs: [commit, spdx]
     steps:
       - name: Checkout Scapy
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
       - name: Setup Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
-          python-version: "3.12"
+          python-version: "3.14"
       - name: Install tox
         run: pip install tox
       - name: Build docs
         run: tox -e docs
-  spdx:
-    name: Check SPDX identifiers
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout Scapy
-        uses: actions/checkout@v4
-      - name: Launch script
-        run: bash scapy/tools/check_spdx.sh
   mypy:
     name: Type hints check
     runs-on: ubuntu-latest
+    needs: [commit, spdx]
     steps:
       - name: Checkout Scapy
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
       - name: Setup Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: "3.12"
       - name: Install tox
@@ -77,13 +95,14 @@ jobs:
   utscapy:
     name: ${{ matrix.os }} ${{ matrix.installmode }} ${{ matrix.python }} ${{ matrix.mode }} ${{ matrix.flags }}
     runs-on: ${{ matrix.os }}
+    needs: [commit, spdx]
     timeout-minutes: 20
     continue-on-error: ${{ matrix.allow-failure == 'true' }}
     strategy:
       fail-fast: false
       matrix:
         os: [ubuntu-latest]
-        python: ["3.8", "3.9", "3.10", "3.11", "3.12"]
+        python: ["3.8", "3.9", "3.10", "3.11", "3.13"]
         mode: [non_root]
         installmode: ['']
         flags: [" -K scanner"]
@@ -96,7 +115,7 @@ jobs:
             flags: " -K scanner"
           # Linux root tests on last version
           - os: ubuntu-latest
-            python: "3.13"
+            python: "3.14"
             mode: root
             flags: " -K scanner"
           # PyPy tests: root only
@@ -106,23 +125,23 @@ jobs:
             flags: " -K scanner"
           # Libpcap test
           - os: ubuntu-latest
-            python: "3.13"
+            python: "3.14"
             mode: root
             installmode: 'libpcap'
             flags: " -K scanner"
           # macOS tests
           - os: macos-14
-            python: "3.13"
+            python: "3.14"
             mode: both
             flags: " -K scanner"
           # windows tests
           - os: windows-latest
-            python: "3.13"
+            python: "3.14"
             mode: root
             flags: " -K scanner"
           # Scanner tests
           - os: ubuntu-latest
-            python: "3.13"
+            python: "3.14"
             mode: root
             allow-failure: 'true'
             flags: " -k scanner"
@@ -131,23 +150,23 @@ jobs:
             mode: root
             flags: " -k scanner"
           - os: macos-14
-            python: "3.13"
+            python: "3.14"
             mode: both
             allow-failure: 'true'
             flags: " -k scanner"
           - os: windows-latest
-            python: "3.13"
+            python: "3.14"
             mode: both
             allow-failure: 'true'
             flags: " -k scanner"
     steps:
       - name: Checkout Scapy
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
         # Codecov requires a fetch-depth > 1
         with:
           fetch-depth: 2
       - name: Setup Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: ${{ matrix.python }}
       - name: Install Tox and any other packages (linux/osx)
@@ -175,13 +194,14 @@ jobs:
   cryptography:
     name: pyca/cryptography test
     runs-on: ubuntu-latest
+    needs: [commit, spdx]
     steps:
     - name: Checkout repository
-      uses: actions/checkout@v4
+      uses: actions/checkout@v6
     - name: Setup Python
-      uses: actions/setup-python@v5
+      uses: actions/setup-python@v6
       with:
-        python-version: "3.12"
+        python-version: "3.14"
     - name: Install tox
       run: pip install tox
     # pyca/cryptography's CI installs cryptography
@@ -195,16 +215,17 @@ jobs:
   analyze:
     name: CodeQL analysis
     runs-on: ubuntu-latest
+    needs: [commit, spdx]
     permissions:
       security-events: write
     steps:
     - name: Checkout repository
-      uses: actions/checkout@v4
+      uses: actions/checkout@v6
       with:
         fetch-depth: 2
     - name: Initialize CodeQL
-      uses: github/codeql-action/init@v3
+      uses: github/codeql-action/init@v4
       with:
          languages: 'python'
     - name: Perform CodeQL Analysis
-      uses: github/codeql-action/analyze@v3
+      uses: github/codeql-action/analyze@v4

.readthedocs.yml

@@ -12,9 +12,9 @@ formats:
   - pdf
 
 build:
-  os: ubuntu-22.04
+  os: ubuntu-24.04
   tools:
-    python: "3.12"
+    python: "3.14"
   # To show the correct Scapy version, we must unshallow
   # https://docs.readthedocs.io/en/stable/build-customization.html#unshallow-git-clone
   jobs:

CONTRIBUTING.md

@@ -40,6 +40,14 @@ submitting an issue.
 If you're not sure whether a behavior is a bug or not, submit an issue
 and ask, don't be shy!
 
+### AI-assisted reports
+
+<!-- Wireshark has greate AI guidelines ! Let's not reinvent the wheel -->
+<!-- https://gitlab.com/wireshark/wireshark/-/blob/master/doc/wsug_src/wsug_introduction.adoc -->
+
+If you use AI tools to help find or draft a bug report, please mention that and make sure you have personally verified the steps and details before submitting.
+Purely AI-generated reports are not supported and might be closed; a quick human check keeps triage efficient for everyone.
+
 ### Enhancements / feature requests
 
 If you want a feature in Scapy, but cannot implement it yourself or
@@ -53,6 +61,18 @@ of function calls, packet creations, etc.).
 
 ### Coding style & conventions
 
+-   All commits should include the `AI-Assisted: (yes/no) [tool]` tag. This is used to disclose the AI tools that are used when authoring. You must check the commits you produce, or your PR might be closed. The tag may look like such:
+
+    ```
+    AI-Assisted: yes (Claude Opus 4.7)
+    ```
+    or
+
+    ```
+    AI-Assisted: no
+    ```
+    This guideline is adapted with thanks to [Wireshark's AI usage statement](https://www.wireshark.org/docs/wsdg_html_chunked/ChSrcContribute.html).
+
 -   The code should be PEP-8 compliant; you can check your code with
     [pep8](https://pypi.python.org/pypi/pep8) and the command `tox -e flake8`
 
@@ -63,20 +83,18 @@ of function calls, packet creations, etc.).
 -   [Google Python Style Guide](https://google.github.io/styleguide/pyguide.html)
     is a nice read!
 
--   Avoid creating unnecessary `list` objects, particularly if they
-    can be huge (e.g., when possible, use `for line in fdesc` instead of
-    `for line in fdesc.readlines()`; more generally prefer generators over
-    lists).
-
 ### Tests
 
-Please consider adding tests for your new features or that trigger the
-bug you are fixing. This will prevent a regression from being
-unnoticed. Do not use the variable `_`  in your tests, as it could break them.
+We require adding tests for all new features or bug fixes, or a justification as to why they are not relevant. We know it's annoying, but Scapy is all about parsing and dissecting weird protocols us maintainers will never encounter. Having good tests is the only way to keep the code maintainable.
+
+- If you are fixing a bug, provide a one-liner that reproduced the bug you are fixing.
+- If you are introducing dissectors, provide at least a very simple "dissect" / "build" of real packets with simple assertions.
+- Tests can be very simple. It's much better to have dumb tests that break when one does changes than no tests.
+- Do not use the variable `_` in your tests, as it could break them.
 
 If you find yourself in a situation where your tests locally succeed  but 
 fail if executed on the CI, try to enable the debugging option for the 
-dissector by setting `conf.debug_dissector = 1`.
+dissector by setting `conf.debug_dissector = 1`. In doubt, feel free to ask maintainers for help.
 
 ### New protocols