pr: Introduce AI-Assisted requirements

AI-Assisted: no

Author: gpotter2

.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/workflows/unittests.yml

@@ -16,9 +16,33 @@ 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@v4
+      - 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
@@ -40,6 +64,7 @@ jobs:
     # 'runs-on' and 'python-version' should match the ones defined in .readthedocs.yml
     name: Build doc
     runs-on: ubuntu-22.04
+    needs: [commit, spdx]
     steps:
       - name: Checkout Scapy
         uses: actions/checkout@v4
@@ -51,17 +76,10 @@ jobs:
         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
@@ -77,6 +95,7 @@ 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:
@@ -175,6 +194,7 @@ jobs:
   cryptography:
     name: pyca/cryptography test
     runs-on: ubuntu-latest
+    needs: [commit, spdx]
     steps:
     - name: Checkout repository
       uses: actions/checkout@v4
@@ -195,6 +215,7 @@ jobs:
   analyze:
     name: CodeQL analysis
     runs-on: ubuntu-latest
+    needs: [commit, spdx]
     permissions:
       security-events: write
     steps:

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