From 4166691a8274ef6e8ed00d53515fad0cb384f7ac Mon Sep 17 00:00:00 2001 From: HugoFara Date: Fri, 4 Sep 2026 19:32:59 +0200 Subject: [PATCH] docs(changelog): one section header per kind in [Unreleased] Each PR prepended its own block, so [Unreleased] had accumulated four separate '### Fixed' headers and the sections ran Changed, Fixed, Added, Deprecated -- neither valid Keep a Changelog nor readable as release notes, which is what this text becomes. Regrouped into Added, Changed, Deprecated, Fixed. Entry text is untouched: all 11 top-level bullets are preserved verbatim, only their grouping and order changed. Same cleanup as c12642d did for 1.0.0. --- CHANGELOG.md | 78 ++++++++++++++++++++++++---------------------------- 1 file changed, 36 insertions(+), 42 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index ef27fdb..cab2966 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +### Added + +- **`pylinkage.synthesis.BurmesterDyad`**, the new name for what was + `pylinkage.synthesis.Dyad`. Same class, same behaviour; the old name still + works and now warns. + +- **A deprecation policy, at `docs/source/deprecations.md`.** One page stating + what pylinkage promises about public names: a name is announced with a + `DeprecationWarning` naming its replacement and removal release, and is + removed no earlier than the next major version. It carries the table of + everything currently deprecated, and how to surface the warnings, which are + silent by default in Python. + +- `pylinkage._deprecation`, the machinery behind that: deprecated names are + removed from their module's namespace and served by a module-level + `__getattr__` (PEP 562), so reading one warns while `from ... import Name` + keeps resolving exactly as before. + ### Changed - **`path_generation()` is 2-8x faster**, with byte-identical results. Verifying @@ -38,6 +56,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 `step_fast()` speedup falls from 6.4x to 5.1x as a result: the numerator got faster, the solver did not regress. +### Deprecated + +- **The three `Dyad` names that were not what they said.** Three unrelated + classes were reachable as `Dyad`, and only two were dyads at all: + `pylinkage.assur.Dyad` (an Assur group, unaffected and keeping its name), + `pylinkage.synthesis.Dyad` (a Burmester dyad, now `BurmesterDyad`), and + `pylinkage.components.Dyad` / `pylinkage.dyads.Dyad` with their + `ConnectedDyad` counterparts, which were plain aliases of `Component` and + `ConnectedComponent` — a `Ground` point is a `Component`, and calling it a + dyad is simply wrong. All four aliases now emit a `DeprecationWarning` and + are scheduled for removal in 2.0.0. Nothing breaks: each name still resolves + to the same object it always did, and stays in its module's `__all__`. + + The concrete cost of the collision was that Sphinx could not tell the three + apart, so cross-references landed on the wrong class. With the aliases + deprecated and the rename in place, the documentation build goes from 8 + warnings to **0**. + ### Fixed - **The benchmarks page figures are regenerated** against the above, and its @@ -47,8 +83,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 exponentially in the number of precision points — five points can take seconds and return nothing — which no documentation said. -### Fixed - - **`step_fast()` silently returned NaN for every dyad except `RRRDyad`.** `linkage_to_solver_data()` typed every dyad as `JOINT_REVOLUTE` and read `distance1` / `distance2` off it. Only `RRRDyad` has those attributes, so a @@ -69,8 +103,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 `step()` and `step_fast()` now agree bit for bit on all three supported dyad types, and are tested to. -### Fixed - - **The benchmarks page gave wrong advice about `path_generation()`.** It attributed the cost to the orientation sweep and said lowering `n_orientation_samples` trades coverage for time roughly linearly. Profiling @@ -84,8 +116,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 depends heavily on which points are asked for: two four-point problems returning ten solutions each measured 336 ms and 1676 ms. Tracked in #29. -### Fixed - - **The cited DOI pointed at 1.0.0 and would have gone stale every release.** `CITATION.cff` and the README badge carried `10.5281/zenodo.21207487`, the *version* DOI Zenodo minted for 1.0.0. Zenodo also mints a *concept* DOI per @@ -101,42 +131,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 the `uv lock` step it was missing — `uv.lock` records the project version and bump-my-version does not touch it. -### Added - -- **`pylinkage.synthesis.BurmesterDyad`**, the new name for what was - `pylinkage.synthesis.Dyad`. Same class, same behaviour; the old name still - works and now warns. - -- **A deprecation policy, at `docs/source/deprecations.md`.** One page stating - what pylinkage promises about public names: a name is announced with a - `DeprecationWarning` naming its replacement and removal release, and is - removed no earlier than the next major version. It carries the table of - everything currently deprecated, and how to surface the warnings, which are - silent by default in Python. - -- `pylinkage._deprecation`, the machinery behind that: deprecated names are - removed from their module's namespace and served by a module-level - `__getattr__` (PEP 562), so reading one warns while `from ... import Name` - keeps resolving exactly as before. - -### Deprecated - -- **The three `Dyad` names that were not what they said.** Three unrelated - classes were reachable as `Dyad`, and only two were dyads at all: - `pylinkage.assur.Dyad` (an Assur group, unaffected and keeping its name), - `pylinkage.synthesis.Dyad` (a Burmester dyad, now `BurmesterDyad`), and - `pylinkage.components.Dyad` / `pylinkage.dyads.Dyad` with their - `ConnectedDyad` counterparts, which were plain aliases of `Component` and - `ConnectedComponent` — a `Ground` point is a `Component`, and calling it a - dyad is simply wrong. All four aliases now emit a `DeprecationWarning` and - are scheduled for removal in 2.0.0. Nothing breaks: each name still resolves - to the same object it always did, and stays in its module's `__all__`. - - The concrete cost of the collision was that Sphinx could not tell the three - apart, so cross-references landed on the wrong class. With the aliases - deprecated and the rename in place, the documentation build goes from 8 - warnings to **0**. - ## [1.1.1] - 2026-09-04 ### Added