docs: add CHANGELOG.rst and render it in the Sphinx docs

MANIFEST.in

@@ -14,5 +14,21 @@ prune test
 include README.rst
 include LICENSE
 
+# The changelog needs two lines of its own, and neither is redundant.
+#
+# ``global-include *.rst`` above matches only ``*.rst``, so the root
+# ``CHANGELOG.md`` is picked up by nothing and would be absent from every source
+# distribution without this line -- measured, not assumed.
+include CHANGELOG.md
+
+# ``CHANGELOG.md`` carries only the version being released, so on its own the
+# distribution would describe one release and no history. ``prune docs`` above
+# drops the rest, which is where the history lives, so re-add just that one
+# directory afterwards -- the same shape as ``include README.rst``, and for the
+# same reason. Each of those files is a self-contained reStructuredText entry
+# that renders standalone; the Sphinx index beside them is deliberately *not*
+# shipped, because it is a ``toctree`` that only Sphinx can read.
+recursive-include docs/source/changelog *.rst
+
 include pcapkit/_extern
 exclude pcapkit/protocols/*/NotImplemented

docs/source/changelog.rst

@@ -0,0 +1,74 @@
+.. The changelog's index. Every entry is its own document under
+   ``changelog/``, one per released version, and this page is the title, the
+   preamble and the table of contents over them -- there is exactly one copy of
+   each entry and nothing to keep in step by hand.
+
+   The repository root carries ``CHANGELOG.md`` rather than a second copy of
+   this history. It holds only the version being released, in Markdown, because
+   its consumers are the ``Create Release`` workflow's release body and the
+   source distribution, and both of those read Markdown. It is generated from
+   ``changelog/<version>.rst``, so this tree stays the single source.
+
+   The preamble below is verbatim from the single-file changelog it replaces.
+
+=========
+Changelog
+=========
+
+All notable changes to PyPCAPKit are recorded here.
+
+   **Note** -- Versions before 1.5.0 are reconstructed from the git history, so
+   they summarise each release rather than enumerate every change. The record
+   starts at 0.13.0 (2018-12-08); the earlier 0.x releases are not covered.
+
+   **Note** -- Post-releases (``X.Y.Z.postN``) are, from 1.0.1 onwards, automated
+   publications of the weekly registry refresh: a bot regenerates the vendor
+   constant enumerations under ``pcapkit.const`` from the upstream IANA
+   registries and bumps the version. They carry no library changes, and are
+   collapsed into a single line per release below. Where a post-release did
+   carry something real, it is called out.
+
+Each release has its own page below, newest first. The repository root's
+:file:`CHANGELOG.md` carries only the version currently being released; this is
+the whole history.
+
+.. toctree::
+   :maxdepth: 1
+
+   changelog/1.5.0
+   changelog/1.4.1
+   changelog/1.4.0
+   changelog/1.3.5
+   changelog/1.3.4
+   changelog/1.3.3
+   changelog/1.3.1
+   changelog/1.3.0
+   changelog/1.2.2
+   changelog/1.2.1
+   changelog/1.2.0
+   changelog/1.1.1
+   changelog/1.1.0
+   changelog/1.0.3
+   changelog/1.0.2
+   changelog/1.0.1
+   changelog/1.0.0
+   changelog/0.16.3
+   changelog/0.16.2
+   changelog/0.16.1
+   changelog/0.16.0
+   changelog/0.15.5
+   changelog/0.15.4
+   changelog/0.15.3
+   changelog/0.15.2
+   changelog/0.15.1
+   changelog/0.15.0
+   changelog/0.14.5
+   changelog/0.14.4
+   changelog/0.14.3
+   changelog/0.14.2
+   changelog/0.14.1
+   changelog/0.14.0
+   changelog/0.13.3
+   changelog/0.13.2
+   changelog/0.13.1
+   changelog/0.13.0

docs/source/changelog/0.13.0.rst

@@ -0,0 +1,7 @@
+0.13.0 -- 2018-12-08
+====================
+
+No library changes -- a licence and packaging metadata refresh.
+
+*Also released:* ``0.13.0.post1``, ``0.13.0.post2`` (through 2018-12-12);
+``post2`` fixed encoding errors in ``setup.py``.

docs/source/changelog/0.13.1.rst

@@ -0,0 +1,8 @@
+0.13.1 -- 2019-01-23
+====================
+
+* **Added** -- ``tbtrim`` is used to trim PyPCAPKit's own frames out of
+  tracebacks through a custom ``excepthook``, so a traceback points at the
+  caller's code.
+* **Fixed** -- compatibility issues, with a new ``pcapkit.utilities.compat``
+  module.

docs/source/changelog/0.13.2.rst

@@ -0,0 +1,4 @@
+0.13.2 -- 2019-01-24
+====================
+
+Maintenance release: the ``tbtrim`` dependency was updated.

docs/source/changelog/0.13.3.rst

@@ -0,0 +1,9 @@
+0.13.3 -- 2019-02-26
+====================
+
+**Fixed** -- numeric literals in the constant modules that were incompatible
+with Python 3.5.
+
+*Also released:* ``0.13.3.post1``, ``0.13.3.post2`` (through 2019-03-01);
+``post1`` declared official support for Python 3.5 and below, and ``post2``
+refreshed the dependencies.

docs/source/changelog/0.14.0.rst

@@ -0,0 +1,5 @@
+0.14.0 -- 2019-03-02
+====================
+
+**Changed** -- the TCP reassembly pipeline handles the RST flag. Docker build
+files were added.

docs/source/changelog/0.14.1.rst

@@ -0,0 +1,5 @@
+0.14.1 -- 2019-03-07
+====================
+
+**Added** -- the ``PCAPKIT_DEVMODE`` environment variable, which turns on
+development-mode behaviour without a code change.

docs/source/changelog/0.14.2.rst

@@ -0,0 +1,4 @@
+0.14.2 -- 2019-03-28
+====================
+
+**Fixed** -- the exception classes, and the TCP reassembly algorithm.

docs/source/changelog/0.14.3.rst

@@ -0,0 +1,5 @@
+0.14.3 -- 2019-08-08
+====================
+
+**Fixed** -- reported bugs (#29, #30), and a Wikipedia block that broke a vendor
+crawler. Constant enumerations and the sample output were regenerated.

docs/source/changelog/0.14.4.rst

@@ -0,0 +1,6 @@
+0.14.4 -- 2019-09-01
+====================
+
+* **Added** -- the vendor crawler scripts ship in the distribution.
+* **Changed** -- the CLI and vendor dependencies are separate extras in
+  ``setup.py``; constant enumerations regenerated.

docs/source/changelog/0.14.5.rst

@@ -0,0 +1,6 @@
+0.14.5 -- 2019-10-24
+====================
+
+* **Added** -- a CLI for the vendor crawlers.
+* **Changed** -- vendor imports are deferred, so the crawler dependencies are
+  not needed to import ``pcapkit``; dependencies revised.

docs/source/changelog/0.15.0.rst

@@ -0,0 +1,11 @@
+0.15.0 -- 2020-06-07
+====================
+
+* **Changed** -- the parsing and construction logic was merged, so a protocol is
+  no longer implemented twice; TCP flow tracing and several interfaces were
+  revised.
+* **Added** -- full API documentation, published at
+  https://pypcapkit.jarryshaw.me.
+* **Fixed** -- the DictDumper dependency and the failures it caused (#37, #40).
+
+Preceded by ``0.15.0rc1`` (2020-06-06).

docs/source/changelog/0.15.1.rst

@@ -0,0 +1,8 @@
+0.15.1 -- 2020-06-18
+====================
+
+Maintenance release: the constant enumerations and the vendor crawlers that
+generate them were revised.
+
+*Also released:* ``0.15.1.post1`` (2020-06-19), a refresh of the constant
+enumerations.

docs/source/changelog/0.15.2.rst

@@ -0,0 +1,7 @@
+0.15.2 -- 2020-06-27
+====================
+
+* **Added** -- a register interface on the protocol classes, and the same on
+  ``pcapkit.foundation.analysis``, so both can be extended without patching the
+  library.
+* **Fixed** -- flow tracing output format and content consistency.

docs/source/changelog/0.15.3.rst

@@ -0,0 +1,5 @@
+0.15.3 -- 2020-08-17
+====================
+
+* **Fixed** -- ARP parsing (#55).
+* **Added** -- logging, through a ``pcapkit`` logger.

docs/source/changelog/0.15.4.rst

@@ -0,0 +1,5 @@
+0.15.4 -- 2020-08-28
+====================
+
+**Fixed** -- the missing ``stacklevel`` attribute on ``pcapkit.utilities`` (#58).
+Travis CI was set up.

docs/source/changelog/0.15.5.rst

@@ -0,0 +1,5 @@
+0.15.5 -- 2020-10-11
+====================
+
+**Fixed** -- a fallback encoder was added so that data DictDumper cannot encode
+no longer raises out of the dumper (#65).

docs/source/changelog/0.16.0.rst

@@ -0,0 +1,23 @@
+0.16.0 -- 2022-05-31
+====================
+
+A project-wide revision, and the last release of the pre-1.0 design.
+
+* **Changed** -- type annotations throughout, and linter compliance
+  (pylint, mypy, bandit, vermin) across every module.
+* **Changed** -- protocol classes were separated from their data models, which
+  moved to ``pcapkit.protocols.data``; a single ``Protocol`` class handles both
+  parsing and construction, and subclassing it to add a protocol is far less
+  work.
+* **Added** -- ``pcapkit.foundation.registry``, so protocols can be subscribed
+  by name; ``Protocol.analyze`` for analysing a payload directly, used by the
+  reassembly classes; ``pcapkit.corekit.multidict``, adapted from Werkzeug.
+* **Changed** -- reassembly became a package (IP, IPv4, IPv6, TCP) with revised
+  data models; PCAP and the auxiliary protocols moved under ``pcapkit.misc``.
+* **Removed** -- the ``validators`` module, several decorators from
+  ``pcapkit.utilities``, and multiprocessing support in ``Extractor``.
+* **Fixed** -- the DPKT toolkit (#101), IP reassembly, and missing ``id``
+  methods on subclassed protocols.
+
+The PyPCAPKit Enhancement Proposals discussion channel was opened with this
+release (#106).

docs/source/changelog/0.16.1.rst

@@ -0,0 +1,6 @@
+0.16.1 -- 2022-06-07
+====================
+
+**Changed** -- warnings are raised through ``pcapkit.utilities.warnings``
+instead of ``warnings.warn`` directly, and a missing optional dependency now
+warns for the CLI and vendor extras too.

docs/source/changelog/0.16.2.rst

@@ -0,0 +1,5 @@
+0.16.2 -- 2022-08-03
+====================
+
+**Fixed** -- ``Info`` ``__init__`` generation for classes without annotations
+(#113); the IP reassembly algorithm (#82).

docs/source/changelog/0.16.3.rst

@@ -0,0 +1,5 @@
+0.16.3 -- 2022-10-31
+====================
+
+**Fixed** -- import crashes on some interpreters (#114, #116); the reassembly
+property caches; README rendering for PyPI. The build chain was revised.

docs/source/changelog/1.0.0.rst

@@ -0,0 +1,31 @@
+1.0.0 -- 2023-05-09
+===================
+
+The 1.0 rewrite: parsing and construction are one declarative definition per
+protocol, and the extraction backend became pluggable. Roughly 55,000 lines
+changed across 617 files, released after 21 beta builds and a release candidate.
+
+* **Added** -- the schema and field layer, ``pcapkit.protocols.schema`` and
+  ``pcapkit.corekit.fields``. A protocol declares its wire format once, as
+  fields (numbers, strings, IP addresses, payloads, options, lists, switches),
+  and both parsing and construction follow from it.
+* **Added** -- PCAP-NG support [1]_: the protocol implementation covering every
+  block type, the generic and per-block options, name-resolution records and
+  decryption secrets, plus a matching extraction engine, toolkit functions and
+  ``pcapkit.protocols.schema.misc.pcapng``.
+* **Added** -- ``pcapkit.foundation.engines``, making the extraction backend a
+  registered, swappable component: the built-in PCAP and PCAP-NG engines
+  alongside DPKT, Scapy and PyShark, with engine registry APIs.
+* **Added** -- ``SchemaWarning``, ``DeprecatedFormatWarning`` and
+  ``RegistryWarning``; ``Protocol._get_payload`` for customised payload
+  retrieval; ``packet`` passed down the protocol chain so a layer can see its
+  parent's context, which is how IPv6 hands source and destination addresses to
+  the transport layer.
+* **Changed** -- flow tracing became the ``pcapkit.foundation.traceflow``
+  package, and reassembly gained data-model modules;
+  ``pcapkit.toolkit.default`` was renamed ``pcapkit.toolkit.pcap``;
+  ``pcapkit.foundation.engine`` became ``engines``; ``IPField`` was split into
+  ``IPAddressField`` and ``IPInterfaceField``; the option and parameter
+  registries for HIP and IPv4 warn on overwrite.
+
+.. [1] PCAP-NG is specified by ``draft-tuexen-opsawg-pcapng``, not by an RFC.

docs/source/changelog/1.0.1.rst

@@ -0,0 +1,8 @@
+1.0.1 -- 2023-05-14
+===================
+
+**Changed** -- ``Info`` and ``Schema`` subclasses are finalised when the class is
+created rather than on each instantiation, which is a straight runtime saving on
+parsing.
+
+*Also released:* ``1.0.1.post1`` through ``1.0.1.post3`` (through 2023-05-27).

docs/source/changelog/1.0.2.rst

@@ -0,0 +1,12 @@
+1.0.2 -- 2023-06-05
+===================
+
+* **Added** -- Mobility Header (MH) parsing and construction [:rfc:`6275`],
+  including the message types, mobility options, CGA parameters and link-layer
+  address option codes, and the binding error status codes.
+* **Fixed** -- ``pcapkit.extract`` failing on interpreters where
+  ``decimal.localcontext`` takes no keyword arguments (#139); wheel filenames
+  now carry the correct Python tags.
+
+*Also released:* ``1.0.2.post1`` through ``1.0.2.post8`` (through 2023-06-27);
+``post6`` also reset the conda build number.

docs/source/changelog/1.0.3.rst

@@ -0,0 +1,11 @@
+1.0.3 -- 2023-06-29
+===================
+
+* **Added** -- the IANA service name and transport protocol port number registry
+  as the ``AppType`` enumeration [:rfc:`6335`], wired into TCP and UDP parsing
+  so ports resolve to service names; a generated enumeration for the TCP header
+  flags; an undefined-command member for FTP commands.
+* **Changed** -- registry management was redesigned; the MPTCP and PCAP-NG
+  option enumerations were revised.
+
+*Also released:* ``1.0.3.post1`` through ``1.0.3.post3`` (through 2023-07-04).

docs/source/changelog/1.1.0.rst

@@ -0,0 +1,12 @@
+1.1.0 -- 2023-07-09
+===================
+
+* **Changed** -- the schema and field classes were rebuilt on metaclasses, with
+  ``EnumSchema`` for enum-dispatched schemas, and every protocol schema was
+  revised onto them: IPv4, HOPOPT, IPv6-Opts, IPv6-Route, HIP, MH, TCP, HTTP/2
+  and PCAP-NG.
+* **Added** -- schema registration through the protocol registry APIs;
+  persistent additional and excluded fields on ``Info``; numeric and comparison
+  support on the PCAP-NG option code and application-layer port enumerations.
+
+*Also released:* ``1.1.0.post1`` through ``1.1.0.post3`` (through 2023-08-12).

docs/source/changelog/1.1.1.rst

@@ -0,0 +1,8 @@
+1.1.1 -- 2023-08-15
+===================
+
+**Fixed** -- ``AppType`` enumeration lookups; ``typing.TypeAlias`` compatibility
+on older interpreters; the output file name chosen by flow tracing; dumping of
+``Schema`` objects through a custom dumper.
+
+*Also released:* ``1.1.1.post1``, ``1.1.1.post2`` (through 2023-08-23).

docs/source/changelog/1.2.0.rst

@@ -0,0 +1,9 @@
+1.2.0 -- 2023-08-26
+===================
+
+* **Added** -- streaming input. ``pcapkit.corekit.io.SeekableReader`` buffers a
+  non-seekable stream so a capture can be read from ``stdin`` or a pipe, which
+  is what live ``tcpdump`` output needs (#156).
+* **Fixed** -- reassembly, broken since 0.16.3 (#155). ``Extractor`` now raises
+  an explicit unsupported-call error, and logs a notice, when reassembly or flow
+  tracing is requested where it cannot be provided.

docs/source/changelog/1.2.1.rst

@@ -0,0 +1,6 @@
+1.2.1 -- 2023-08-27
+===================
+
+**Fixed** -- bugs in the ``SeekableReader`` introduced one day earlier in 1.2.0.
+
+*Also released:* ``1.2.1.post1`` through ``1.2.1.post3`` (through 2023-09-09).

docs/source/changelog/1.2.2.rst

@@ -0,0 +1,6 @@
+1.2.2 -- 2023-09-14
+===================
+
+**Fixed** -- extraction failing outright (#166).
+
+*Also released:* ``1.2.2.post1``, ``1.2.2.post2`` (through 2023-10-04).

docs/source/changelog/1.3.0.rst

@@ -0,0 +1,14 @@
+1.3.0 -- 2023-10-04
+===================
+
+A redesign of the extension points, on metaclasses.
+
+* **Changed** -- the protocol, reassembly, flow-tracing, engine, vendor and
+  field base classes are all built on metaclasses, which is what registers a
+  subclass and fixes its name and module.
+* **Added** -- ``ModuleDescriptor``, so a registry entry can name a module and
+  class that are imported lazily on first use rather than at registration; the
+  registry functions accept it throughout. ``VersionInfo`` gained a ``version``
+  property.
+* **Changed** -- ``_Engine`` renamed ``EngineBase``; the ``beholder`` decorator
+  logs the error it swallows under devmode and verbose mode.

docs/source/changelog/1.3.1.rst

@@ -0,0 +1,11 @@
+1.3.1 -- 2023-12-21
+===================
+
+* **Changed** -- ``register_port()`` was renamed ``register_apptype()``, with no
+  alias left behind; callers registering application-layer protocols by port
+  must be updated.
+* **Changed** -- the documentation was revised across the whole project --
+  ``pcapkit.protocols``, ``pcapkit.corekit`` and ``pcapkit.dumpkit`` in
+  particular.
+
+*Also released:* ``1.3.1.post1`` through ``1.3.1.post28`` (through 2024-10-26).