fix(packaging): ship CITATION.cff in the source distribution

CHANGELOG.md

@@ -79,6 +79,7 @@ This is the resolution of #548, which reported `TransType.L2TP` (115) as registe
 - **Fixed** -- `util/bump_version.py` left `CITATION.cff` naming the previous release. Nothing else in the repository maintains that file -- no workflow, hook or packaging file mentions it -- so every bump since it landed in #615 would have stranded the `version` and `date-released` it renders as GitHub's "Cite this repository" button and that citation managers, Zenodo and dependency inventories read directly. Both fields now move with `__version__`. They have the same standing, since the file's own header says both describe the newest *published* release, and moving only one would assert that 1.5.0b5 was released on the day 1.5.0b4 was; the date is taken in UTC, because seven of the thirty most recent bumps were made late evening in US-Eastern where a local date is a day behind the publish it describes. That the two are the same day at all is measured rather than assumed: the bump is what triggers `create-release.yml`, the median gap to the PyPI upload is three minutes, and the UTC calendar dates agree 30 times out of 30. The rewrite is line-oriented, so the comment header, key ordering and each field's existing quoting survive -- `cff-version` and a `references` entry's own `version` are anchored out at column zero -- and the result is checked with `cffconvert --validate`. An absent file is reported on stderr and skipped rather than failing the vendor cron before its `git commit`, which would discard the whole registry crawl for the sake of a documentation file; a file present with no `version` field raises instead, before anything is written, because rewriting nothing while reporting success is the staleness this fixes. Two things came with it. The script gains a `main()` guard, having previously run the entire bump at import, which is why it had no testable surface; and the `import pcapkit` fallback in its version reader, which returned `"1.5.0b4'\n"` -- closing quote and newline included, which `packaging` rejects -- is fixed, a path that had never worked and went unnoticed because the only caller installs the package first. A new gate asserts the committed file still names the packaged version, covering the version changes made by hand, which never run this script at all -- 40 of the 159 commits that have moved `__version__` on `main`, a quarter over the project's life and 11 of the most recent 25 (#625).
 
 - **Fixed** -- `LICENSE`'s copyright notice began the term at 2018, a year after the work it covers. The repository's first commit is `c57f7d0b7` "Initial commit", dated 2017-11-07, so the notice understated the term and contradicted the only other copyright site in the tree: `docs/source/conf.py` computes its Sphinx footer as `f'2017-{datetime.date.today().year}, Jarry Shaw'` and has said 2017 for as long as it has existed. The two now agree on where the term starts. The wrong start year survived every maintenance pass the line has had, because each looked only at the other end of the range: `bc836cfa2` (2020-05-31) introduced `2018-2020` when the BSD-3-Clause text replaced MPL 2.0 -- the file until then was stock MPL text carrying no author notice at all, so 2018 is the first start year the project ever asserted and it was already a year late when it was written -- and the range was then bumped by hand three times, to `2018-2022`, `2018-2023` and `2018-2026` (#615), each bump correcting the end year and copying `2018` forward untouched. The end year is **dropped** rather than automated, which is the other half of the change: the notice ships inside the sdist and the wheel, so its text is fixed at build time in every copy already downloaded and cannot be computed the way the docs footer is; copyright subsists from creation whether or not a notice names the current year; and BSD-3-Clause's canonical form is `Copyright (c) <year> <owner>`, singular. So a range here is six years of hand maintenance on one line buying nothing, and no workflow, script hook or other automation is added in its place -- that was considered and rejected, since automating a value that need not be current is worse than not carrying it. `conf.py` is deliberately untouched, a self-maintaining docs footer showing a range being both conventional and correct. The licence body is unaltered: the whole-file diff is one hunk at line 3, and the remaining 28 lines carry the canonical BSD-3-Clause wording verbatim. Three things distinguish the file from SPDX's bare `licenseText`, and all three predate this change -- the `BSD 3-Clause License` title line, which the opensource.org template carries and SPDX omits; the `*` bullets in place of `1.`/`2.`/`3.`; and the extra `All rights reserved.` line -- and the `DAMAGE.` that #615 repaired from a stray `DAMAGE.s` is still clean (#630).
+- **Fixed** -- `CITATION.cff` shipped in no source distribution. `MANIFEST.in` carries an `include` line each for `README.md`, `LICENSE` and `CHANGELOG.md` but had none for the citation file, and its two `global-include` patterns are `*.rst` and `*.py`, neither of which can match a `.cff` -- so the file sat in the repository and in nothing published. Nor was there a default to fall back on. Removing all three of those `include` lines and rebuilding shows `README.md` and `LICENSE` shipping anyway, setuptools adding the latter from `license_files` and recording it as `License-File: LICENSE` in `PKG-INFO`, while `CHANGELOG.md` vanishes -- so of the three only `CHANGELOG.md` is load-bearing, and a citation file, which no packaging default covers at all, is in the same position. The gap is invisible from the web UI, because GitHub renders the "Cite this repository" button from the repository itself; citation managers, Zenodo and dependency inventories read the published artifact, which is exactly the surface that was missing it, so the machine-readable half of the attribution stopped travelling with the code at the one point nobody can see the repository. #615 flagged the omission when it added the file and #619 did not address it. It matters now because #625 has just taught `util/bump_version.py` to keep the file's `version` and `date-released` in step with the bump, and a release exercising that path would otherwise publish an sdist omitting the very artefact under test. It also lets `RepositoryCitationTests` in `tests/project/test_bump_version.py` -- the gate #625 added for the hand-authored bumps that never run the script -- execute against an unpacked sdist, where today it skips itself with "CITATION.cff is not shipped in the source distribution". Measured both ways with `python -m build --sdist`: `tar tzf` found no `CITATION.cff` before and `pypcapkit-1.5.0b4/CITATION.cff` after, the two archive listings differ by that one added entry and nothing else -- 860 against 861 -- the shipped copy is byte-identical to the repository's, and `twine check --strict` reports `PASSED` on both archives (#631).
 
 Preceded by `1.5.0a1` (2026-09-15), `1.5.0b1` and `1.5.0b2` (both 2026-09-18) and `1.5.0b3` (2026-09-19), all published as prereleases and so resolved only by `pip install --pre`. `1.5.0b1` half-shipped: the tag, the GitHub release and the Conda deployments landed, but PyPI rejected the wheel because `twine check` found a Sphinx-only `:mod:` role in `README.rst`, which `pyproject.toml` declares as the dynamic long description. `1.5.0b2` is what reshipped it -- the release workflow is version-driven, so an existing version cannot republish -- and `1.5.0b3` followed the CI change that stops a TestPyPI outage from costing a release its wheels (#497, #498).
 

MANIFEST.in

@@ -18,6 +18,22 @@ prune test
 include README.md
 include LICENSE
 
+# Load-bearing, and missed for the same reason as ``CHANGELOG.md`` below:
+# neither ``global-include`` at the top of this file can reach a ``.cff``, so
+# without this line ``CITATION.cff`` sits in the repository and in no source
+# distribution at all -- measured by building one each way, not assumed. Nor is
+# there a default to fall back on: setuptools ships ``LICENSE`` from its
+# ``license_files`` whether or not this file mentions it, but no packaging
+# default covers a citation file. The published artifact is the surface that
+# matters, because GitHub renders the "Cite this repository" button from the
+# repository itself while citation managers, Zenodo and dependency inventories
+# read what was actually published -- so omitting it drops the machine-readable
+# half of the attribution at the one point nobody can see the repository. It
+# also lets ``RepositoryCitationTests`` in
+# ``tests/project/test_bump_version.py`` run against an unpacked sdist, where
+# today it skips itself with "not shipped in the source distribution".
+include CITATION.cff
+
 # The changelog needs two lines of its own, and neither is redundant.
 #
 # ``global-include *.rst`` above matches only ``*.rst``, so the root

docs/source/changelog/1.5.0.rst

@@ -1095,6 +1095,35 @@ pull requests between #326 and #509.
   SPDX omits; the ``*`` bullets in place of ``1.``/``2.``/``3.``; and the extra
   ``All rights reserved.`` line -- and the ``DAMAGE.`` that #615 repaired from a
   stray ``DAMAGE.s`` is still clean (#630).
+* **Fixed** -- ``CITATION.cff`` shipped in no source distribution. ``MANIFEST.in``
+  carries an ``include`` line each for ``README.md``, ``LICENSE`` and
+  ``CHANGELOG.md`` but had none for the citation file, and its two
+  ``global-include`` patterns are ``*.rst`` and ``*.py``, neither of which can match
+  a ``.cff`` -- so the file sat in the repository and in nothing published. Nor was
+  there a default to fall back on. Removing all three of those ``include`` lines and
+  rebuilding shows ``README.md`` and ``LICENSE`` shipping anyway, setuptools adding
+  the latter from ``license_files`` and recording it as ``License-File: LICENSE`` in
+  ``PKG-INFO``, while ``CHANGELOG.md`` vanishes -- so of the three only
+  ``CHANGELOG.md`` is load-bearing, and a citation file, which no packaging default
+  covers at all, is in the same position. The gap is invisible from the web UI,
+  because GitHub renders the "Cite this repository"
+  button from the repository itself; citation managers, Zenodo and dependency
+  inventories read the published artifact, which is exactly the surface that was
+  missing it, so the machine-readable half of the attribution stopped travelling
+  with the code at the one point nobody can see the repository. #615 flagged the
+  omission when it added the file and #619 did not address it. It matters now
+  because #625 has just taught ``util/bump_version.py`` to keep the file's
+  ``version`` and ``date-released`` in step with the bump, and a release exercising
+  that path would otherwise publish an sdist omitting the very artefact under test.
+  It also lets ``RepositoryCitationTests`` in
+  ``tests/project/test_bump_version.py`` -- the gate #625 added for the hand-authored
+  bumps that never run the script -- execute against an unpacked sdist, where today
+  it skips itself with "CITATION.cff is not shipped in the source distribution".
+  Measured both ways with ``python -m build --sdist``: ``tar tzf`` found no
+  ``CITATION.cff`` before and ``pypcapkit-1.5.0b4/CITATION.cff`` after, the two
+  archive listings differ by that one added entry and nothing else -- 860 against
+  861 -- the shipped copy is byte-identical to the repository's, and
+  ``twine check --strict`` reports ``PASSED`` on both archives (#631).
 
 Preceded by ``1.5.0a1`` (2026-09-15), ``1.5.0b1`` and ``1.5.0b2`` (both
 2026-09-18) and ``1.5.0b3`` (2026-09-19), all published as prereleases and so