From c20492d853c258cf7be75cab947c5f5c9c6f7a9a Mon Sep 17 00:00:00 2001 From: Jarry Shaw Date: Mon, 21 Sep 2026 21:53:38 -0400 Subject: [PATCH] docs: repair the Code of Conduct's rendering and refresh CONTRIBUTING - CODE_OF_CONDUCT.md: the whole document sat inside a `1. ` ordered-list item, every line after the first indented three spaces to continue it, so GitHub rendered the entire Code of Conduct as one numbered, indented list entry. Drop the wrapper; the Contributor Covenant 1.4 prose is byte-identical otherwise. The two `http://contributor-covenant.org` links become `https://` and point at the canonical 1.4 path, which is what resolves today. The reporting contact is left alone: `jarryshaw@icloud.com` matches the `authors` entry in `pyproject.toml`. - CONTRIBUTING.md: the substance dated from the 2019 `gaocegege/maintainer` generator and described another project. Its worked example was `store/localstore:`, a TiDB path with no counterpart here, and its "no longer than 70 characters" rule is exceeded by 127 of the last 200 subjects (median 77, longest 119). Replaced with the convention actually in use -- 55 of the last 60 commits carry a Conventional Commits type -- using a real commit as the example, and noting that older history is mixed. Added the test tiers and `make test` / `make test-all`, the pipenv development environment, the generated-`CHANGELOG.md` trap that the `Changelog drift` job gates, the reStructuredText convention with its repository-root Markdown exception, and the linters with their real line lengths (120 and 100, not PEP 8's 79). Dropped the stale generator footer, and stopped naming the README by extension. - Templates: the bug report offered Python 3.4-3.7 as examples where CI tests 3.10-3.14, and asked for no `pcapkit` version; the pull-request template asked for neither a passing test run nor a changelog entry. No changelog entry: contributor-facing documentation, not user-visible. Verified `python util/changelog_md.py --check` still exits 0. No tests run -- nothing here touches the package. --- .github/ISSUE_TEMPLATE/bug_report.md | 5 +- .github/PULL_REQUEST_TEMPLATE.md | 5 +- CODE_OF_CONDUCT.md | 57 +++++----- CONTRIBUTING.md | 152 +++++++++++++++++++++------ 4 files changed, 151 insertions(+), 68 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md index a847f7ba2f..ddb4ec3ae6 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -9,9 +9,10 @@ A clear and concise description of what the bug is. **System information** A clear and concise description of your system information. - - OS Version: [e.g. macOS Mojave 10.14.4] - - Python Version: [e.g 3.7, 3.6, 3.5, 3.4] + - OS Version: [e.g. macOS 15.3, Ubuntu 24.04, Windows 11] + - Python Version: [e.g. 3.14, 3.12, 3.10] - Python Implementation: [e.g. CPython, PyPy] + - `pcapkit` Version: [e.g. 1.5.0b4; `python -c "import pcapkit; print(pcapkit.__version__)"`] **Traceback stack** Run program again with `PCAPKIT_DEVMODE=true` set to provide the traceback stack. diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 7107af4ce2..dfb26d560a 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -5,8 +5,9 @@ - Use *Preview* tab to see how your *pull request* will actually look like - [ ] [Searched](https://github.com/JarryShaw/PyPCAPKit/search?q=is%3Apr&type=Issues) for similar pull requests -- [ ] Followed PEP8 coding style -- [ ] Tested with proper test samples +- [ ] Followed the [coding style](https://github.com/JarryShaw/PyPCAPKit/blob/main/CONTRIBUTING.md#coding-style) (`make pylint`, `make mypy`, `make isort`) +- [ ] `make test` passes, and a test case covers the change +- [ ] Added a [changelog entry](https://github.com/JarryShaw/PyPCAPKit/blob/main/CONTRIBUTING.md#changelog-entries) under `docs/source/changelog/` and regenerated `CHANGELOG.md`, if the change is user-visible ### What is the purpose of your *pull request*? - [ ] Bug fix diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index 7609040a83..5ec1c28cf2 100755 --- a/CODE_OF_CONDUCT.md +++ b/CODE_OF_CONDUCT.md @@ -1,47 +1,46 @@ -1. # Contributor Covenant Code of Conduct +# Contributor Covenant Code of Conduct - ## Our Pledge +## Our Pledge - In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation. +In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation. - ## Our Standards +## Our Standards - Examples of behavior that contributes to creating a positive environment include: +Examples of behavior that contributes to creating a positive environment include: - * Using welcoming and inclusive language - * Being respectful of differing viewpoints and experiences - * Gracefully accepting constructive criticism - * Focusing on what is best for the community - * Showing empathy towards other community members +* Using welcoming and inclusive language +* Being respectful of differing viewpoints and experiences +* Gracefully accepting constructive criticism +* Focusing on what is best for the community +* Showing empathy towards other community members - Examples of unacceptable behavior by participants include: +Examples of unacceptable behavior by participants include: - * The use of sexualized language or imagery and unwelcome sexual attention or advances - * Trolling, insulting/derogatory comments, and personal or political attacks - * Public or private harassment - * Publishing others' private information, such as a physical or electronic address, without explicit permission - * Other conduct which could reasonably be considered inappropriate in a professional setting +* The use of sexualized language or imagery and unwelcome sexual attention or advances +* Trolling, insulting/derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or electronic address, without explicit permission +* Other conduct which could reasonably be considered inappropriate in a professional setting - ## Our Responsibilities +## Our Responsibilities - Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior. +Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior. - Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful. +Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful. - ## Scope +## Scope - This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers. +This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers. - ## Enforcement +## Enforcement - Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at jarryshaw@icloud.com. The project team will review and investigate all complaints, and will respond in a way that it deems appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately. +Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at jarryshaw@icloud.com. The project team will review and investigate all complaints, and will respond in a way that it deems appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately. - Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership. +Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership. - ## Attribution +## Attribution - This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, available at [http://contributor-covenant.org/version/1/4][version] - - [homepage]: http://contributor-covenant.org - [version]: http://contributor-covenant.org/version/1/4/ +This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, available at [https://www.contributor-covenant.org/version/1/4/code-of-conduct/][version] +[homepage]: https://www.contributor-covenant.org +[version]: https://www.contributor-covenant.org/version/1/4/code-of-conduct/ diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e18913530a..5cf40386f6 100755 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,67 +1,149 @@ # How to contribute -This document outlines some of the conventions on development workflow, commit message formatting, contact points and other -resources to make it easier to get your contribution accepted. +This document outlines the conventions on development workflow, commit message formatting and the +few repository-specific rules that are easy to trip over — the test tiers and the generated +changelog especially. The README is the authority on installing and building; this file covers what +happens after that. ## Getting started - Fork the repository on GitHub. -- Read the README.rst for build instructions. +- Read the README for installation and build instructions, and its *Testing* section for the test + commands. +- Set up a development environment. `make setup` runs `pipenv install --skip-lock --dev`, and the + `Makefile` exports `PIPENV_VENV_IN_PROJECT=1`, so the environment lands in `.venv/` inside the + checkout. **Only that environment has the dependencies** — the `make` targets below all run + through `pipenv run`, and invoking `pytest` or `sphinx` from a system interpreter will fail on + missing imports rather than on anything you changed. +- Looking for something to pick up? `docs/source/pep.rst` — rendered as the *Help Wanted* page — is + the maintained list of open proposals, kept in step with the code. - Play with the project, submit bugs, submit patches! ## Contribution flow This is a rough outline of what a contributor's workflow looks like: -- Create a topic branch from where you want to base your work. This is usually main. -- Make commits of logical units and add test case if the change fixes a bug or adds new functionality. -- Run tests and make sure all the tests are passed. +- Create a topic branch from where you want to base your work. This is usually `main`. +- Make commits of logical units, and add a test case if the change fixes a bug or adds new + functionality. +- Run the tests and make sure they pass (see below). +- Add a changelog entry if the change is user-visible (see below). - Make sure your commit messages are in the proper format (see below). - Push your changes to a topic branch in your fork of the repository. - Submit a pull request to the repo. Thanks for your contributions! -## Coding Style +## Running the tests -See the [Python style doc](https://www.python.org/dev/peps/pep-0008/) for details. +The suite runs in two tiers, and the tier is a property of a module's *path* rather than of the +command that collects it. `tests/_tiers.py` is the rule, and it documents itself at length. -### Format of the Commit Message +```shell +make test # the unit tier -- the selection CI runs +make test-all # everything, regenerating the sample captures first +``` -We follow a rough convention for commit messages that is designed to answer two -questions: what changed and why. The subject line should feature the what and -the body of the commit should describe the why. +`make test` is the selection in `.github/workflows/unit-tests.yml`: everything under `tests/` except +`tests/integration/` and the `*_runtime.py` / `*_regression.py` modules. It has to pass on a fresh +clone with nothing but the package and its test extra installed. -

-store/localstore: add comment for variable declaration.
+The fixture-dependent tier reads sample captures under `examples/captures/`, most of which are
+**not** tracked (see `.gitignore`); only a handful are committed. `make samples` rebuilds the rest,
+and `make test-all` does that for you. This is the trap worth knowing
+about: a unit-tier module that reads a *generated* capture passes on your machine, because you have
+run `make samples`, and then fails on a fresh CI checkout with a missing-file error that blames the
+fixture rather than the tier rule. `tests/conftest.py` and `tests/test_tier_guard.py` catch most
+shapes of it at collection time and tell you what to do; read `tests/_tiers.py` if the message is
+not enough.
 
-Improve documentation.
-
+## Changelog entries -The format can be described more formally as follows: +Entries live in `docs/source/changelog/.rst`, one file per version, listed newest-first in +the toctree of `docs/source/changelog.rst`. That tree is the single source of the project's history. -

-subsystem: what changed
-BLANK LINE
-why this change was made
-BLANK LINE
-footer(optional)
-
+**`CHANGELOG.md` is generated — never edit it by hand.** It is a derivative of the newest entry +alone, produced by `util/changelog_md.py`, because its two consumers (the `Create Release` +workflow's release body and the source distribution) read Markdown rather than reStructuredText. +Add your bullet to the `.rst` entry, then regenerate: + +```shell +python util/changelog_md.py # rewrite CHANGELOG.md from the newest entry +python util/changelog_md.py --check # exits 0 when they agree, prints a diff when they do not +``` + +The generator needs only the standard library, so it runs against a bare interpreter. The +`Changelog drift` job in `.github/workflows/unit-tests.yml` runs `--check` on every push and pull +request, and a hand-edited `CHANGELOG.md` will fail it. + +## Documentation + +Documentation is reStructuredText under `docs/source/`, built with `make docs`. Docstrings in +`pcapkit/` are reStructuredText too, and they are what the API reference renders from. -The first line is the subject and should be no longer than 70 characters, the -second line is always blank, and other lines should be wrapped at 80 characters. -This allows the message to be easier to read on GitHub as well as in various -git tools. +The Markdown files at the repository root — this one, `CODE_OF_CONDUCT.md`, `SECURITY.md`, +`CHANGELOG.md` and the README — are a deliberate exception to that rule, because their consumers are +GitHub's own rendering and the release body rather than Sphinx. The exception stops at the root: +anything added under `docs/source/` is `.rst`. -If the change affects more than one subsystem, you can use comma to separate them like util/codec,util/types:. +## Coding style -If the change affects many subsystems, you can use * instead, like *:. +[PEP 8](https://peps.python.org/pep-0008/) is the baseline, but the repository's own linters are the +authority where they differ from it — notably on line length, which is 120 for `pylint` and 100 for +`isort`, not PEP 8's 79. Run them through the `Makefile`, which carries the flags they are meant to +be run with: -For the why part, if no specific reason for the change, -you can use one of some generic reasons like "Improve documentation.", -"Improve performance.", "Improve robustness.", "Improve test coverage." +```shell +make isort # import ordering +make pylint # errors, warnings, refactoring and docstring style +make mypy # type checking over pcapkit/ +make bandit # security lint +make vermin # minimum-Python-version check +``` +None of these is run by the pull-request workflows, so they are a local gate rather than something a +pull request will fail on. Running them anyway saves a review round. ---- +### Format of the Commit Message + +We follow a rough convention designed to answer two questions: what changed and why. The subject +line carries the what, and the body of the commit describes the why. A real one from the history, +with its body abridged: + +``` +fix(tcp): resolve the connection flags before building the options (#587) (#597) + +Building any MP_JOIN option raised `AttributeError: 'TCP' object has no +attribute '_flags'`. `TCP.make` built the options at tcp.py:547 and assigned +`self._flags` only at tcp.py:567, but `_make_mptcp_join` (tcp.py:2780-2786) +branches on that attribute to choose between RFC 8684 s3.2's three MP_JOIN +layouts [...] +``` -Auto-generated by [gaocegege/maintainer](https://github.com/gaocegege/maintainer) on 2019-10-24. +The format is: + +``` +type(scope): what changed (#issue) +BLANK LINE +why this change was made +BLANK LINE +footer (optional) +``` + +`type` is one of `feat`, `fix`, `docs`, `test`, `perf`, `refactor`, `ci` or `chore` — those are the +ones in use. `scope` names the part of the package affected — `tcp`, `corekit`, `schema`, `ipv4`, +`vendor` — and several are separated by commas inside the parentheses, as in `fix(link,internet):` +or `test(utilities,foundation):`. The scope may be omitted where nothing narrower than the whole +project applies, as in `docs:`. + +Older history is mixed, and `git log` will show you a bare `protocols:` or `corekit:` subsystem +prefix from before this settled. Follow the form above for new work rather than the older one. + +Reference issues and pull requests as `#nnn`, in the subject where they fit and in the body +otherwise. Keep the subject to one line and as short as clarity allows; there is no hard column +limit, and the history routinely runs past 70 characters and up to about 120, so do not truncate the +meaning to hit a number. + +Say why in the body rather than falling back on a generic line. "Improve documentation." tells a +future reader nothing that the diff does not already show; the defect that was observed, or the +behaviour that was wrong, does.