specmod 0.2.0__tar.gz → 0.2.1__tar.gz

{specmod-0.2.0 → specmod-0.2.1}/.github/workflows/release.yml

@@ -28,20 +28,44 @@ jobs:
       - uses: googleapis/release-please-action@v4
         id: release
         with:
+          # A pull request opened with the default GITHUB_TOKEN starts no
+          # workflow runs at all — "events triggered by the GITHUB_TOKEN will
+          # not create a new workflow run". The release PR therefore arrived
+          # with *zero* checks, and since `ci`, `docs` and `build` are required
+          # on main, it could never satisfy them: permanently blocked, with no
+          # failure to point at. v0.2.0 shipped only because the PR was closed
+          # and reopened by hand, which re-fires the event from a real account.
+          #
+          # RELEASE_PLEASE_TOKEN_SPECMOD is a fine-grained PAT (contents + pull
+          # requests, write) so the PR is opened by a user and CI runs on it
+          # normally. It is *not* a PyPI credential — the upload below still
+          # authenticates by OIDC, so the number of publishing secrets is
+          # still zero. See docs/releasing.md for how to mint and renew it.
+          #
+          # The fallback keeps the workflow working in a fork or before the
+          # secret exists; it degrades to the blocked-PR behaviour, not to a
+          # broken run.
+          token: ${{ secrets.RELEASE_PLEASE_TOKEN_SPECMOD || secrets.GITHUB_TOKEN }}
           config-file: release-please-config.json
           manifest-file: .release-please-manifest.json
 
   # Deliberately in this workflow rather than a separate publish.yml keyed on
-  # `release: published`, which is what §6.5 of the plan used to describe.
-  # release-please creates the release with the default GITHUB_TOKEN, and
-  # per GitHub's docs "events triggered by the GITHUB_TOKEN will not create a
-  # new workflow run" — so that publish workflow would never fire. The
-  # alternative is a personal access token in secrets, which is the one thing
-  # Trusted Publishing exists to avoid. Gating on the action's own output
-  # keeps the token count at zero.
+  # `release: published`, which is what §6.5 of the plan used to describe. That
+  # workflow could not fire at all while release-please ran on GITHUB_TOKEN,
+  # so this job gates on the action's own `release_created` output instead.
   #
-  # Zenodo is unaffected: it listens to the release *webhook*, which is not
-  # subject to that restriction, so the DOI is still minted from the release.
+  # With RELEASE_PLEASE_TOKEN_SPECMOD the release is created by a PAT, which
+  # *does* start workflow runs, so a separate publish.yml would now work. Still
+  # not worth splitting: one workflow is one concurrency group and one place to
+  # read, with no race between two runs when two merges land together. The
+  # `release_created` gate is also exact, where an event key would fire on any
+  # release — including one created by hand.
+  #
+  # Note the PAT is not a publishing credential: the upload below authenticates
+  # by OIDC, so the number of secrets that can push to PyPI is still zero.
+  #
+  # Zenodo is unaffected either way: it listens to the release *webhook*, which
+  # is not subject to the token restriction, so the DOI is minted regardless.
   publish:
     needs: release-please
     if: needs.release-please.outputs.release_created == 'true'

specmod-0.2.1/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.2.1"
+}

{specmod-0.2.0 → specmod-0.2.1}/CHANGELOG.md

@@ -1,6 +1,26 @@
 # Changelog
 
-## [0.2.0](https://github.com/sgjholt/SpecMod/compare/v0.1.1...v0.2.0) (2026-08-23)
+<!-- The 0.2.0 heading below is edited by hand, and is the only entry that is.
+release-please generated `compare/v0.1.1...v0.2.0`, which 404s: 0.1.1 predates
+this repository's tagging and was never tagged, so there is nothing at that
+ref. It is preserved on the frozen `master` branch instead, and comparing
+against that branch is the same diff under a name that resolves. Only the first
+release could have this problem — every later one has a real predecessor tag —
+so leave subsequent headings as generated. release-please only prepends to this
+file, so this edit survives. -->
+
+## [0.2.1](https://github.com/sgjholt/SpecMod/compare/v0.2.0...v0.2.1) (2026-08-23)
+
+
+### Documentation
+
+* add the Zenodo DOI to the README and the citation metadata ([8a89884](https://github.com/sgjholt/SpecMod/commit/8a89884f654b14bf5eb9ed8a32d10dc22d5e5fb4))
+* PyPI and docs badges, and an install section for people who are not us ([d444397](https://github.com/sgjholt/SpecMod/commit/d44439762214b93fd8eef3f64745570b3b8be2b0))
+* repoint the 0.2.0 changelog link, which 404s ([f1bbe31](https://github.com/sgjholt/SpecMod/commit/f1bbe3143ca3ca6dd58f584546e716d2170a790a))
+* say where the code behind the publication lives ([ae7e906](https://github.com/sgjholt/SpecMod/commit/ae7e906209a87844cf2106a826be5111a6ef2036))
+* turn the roadmap's stages into milestones against versions ([b933e69](https://github.com/sgjholt/SpecMod/commit/b933e69d219a54e4a7db894797a507a3bb24e31c))
+
+## [0.2.0](https://github.com/sgjholt/SpecMod/compare/master...v0.2.0) (2026-08-23)
 
 
 ### ⚠ BREAKING CHANGES

{specmod-0.2.0 → specmod-0.2.1}/CITATION.cff

@@ -7,6 +7,13 @@ authors:
     given-names: James
 repository-code: "https://github.com/sgjholt/SpecMod"
 license: MIT
+identifiers:
+  # The concept DOI, which always resolves to the newest release. Zenodo also
+  # mints a version DOI per release; cite that one instead when reproducibility
+  # matters and you need the reader to land on the exact version you ran.
+  - type: doi
+    value: "10.5281/zenodo.22071455"
+    description: "Concept DOI — resolves to the latest release."
 keywords:
   - seismology
   - spectral modelling

{specmod-0.2.0 → specmod-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: specmod
-Version: 0.2.0
+Version: 0.2.1
 Summary: A Python toolbox for processing and modelling seismic spectra
 Project-URL: Homepage, https://github.com/sgjholt/SpecMod
 Project-URL: Repository, https://github.com/sgjholt/SpecMod
@@ -56,6 +56,10 @@ Description-Content-Type: text/markdown
 
 # SpecMod
 
+[![PyPI](https://img.shields.io/pypi/v/specmod.svg)](https://pypi.org/project/specmod/)
+[![Documentation](https://readthedocs.org/projects/specmod/badge/?version=stable)](https://specmod.readthedocs.io/en/stable/)
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.22071455.svg)](https://doi.org/10.5281/zenodo.22071455)
+
 A Python toolbox for processing and modelling seismic spectra, following the
 method of Edwards *et al.* (2010).
 
@@ -71,26 +75,44 @@ source model to direct-phase spectra.
 > breaking changes at every `0.x` release until the API settles at 1.0 — they
 > land in minor bumps by design, with no deprecation cycle. Pin an exact
 > version for anything you intend to publish.
-> [`docs/roadmap.md`](docs/roadmap.md) says which stages are done and what 1.0
-> will mean; [`docs/REFACTOR_PLAN.md`](docs/REFACTOR_PLAN.md) is the working
-> document behind it.
+> [`docs/roadmap.md`](docs/roadmap.md) says what has shipped, in which version,
+> and what 1.0 will mean; [`docs/REFACTOR_PLAN.md`](docs/REFACTOR_PLAN.md) is
+> the working document behind it.
 
 ## Installation
 
 Requires Python 3.11 or newer.
 
+```sh
+pip install specmod
+```
+
+While this is `0.x`, pin the exact version in anything you intend to publish:
+`pip install specmod==<version>`, taking the current one from the badge above.
+The reason is in the status note — `0.x` releases move names and numbers, and
+the pin plus the configuration stamp each output carries are together what
+make a run reproducible.
+
+To work on SpecMod rather than with it, clone the repository and install it
+editable with the test and lint tooling:
+
 ```sh
 pip install -e ".[dev]"
 ```
 
-Optional extras:
+Optional extras, installable as `pip install "specmod[multitaper]"` or in
+combination — `pip install "specmod[multitaper,wavelet]"`:
 
 | Extra | Adds |
 |---|---|
+| `io` | `h5py` and `pyarrow` — needed to save or load spectra, as HDF5 for arrays and Parquet for tables |
 | `multitaper` | Prieto's `multitaper` package — jackknife confidence intervals, F-test for spectral lines |
 | `wavelet` | PyWavelets, for wavelet families beyond the built-in Morlet |
 | `mcmc` | `emcee`, for Markov-chain Monte Carlo parameter search |
 
+`io` is the one most people want: without it SpecMod computes and plots
+normally, but `specmod.io` raises on the first save telling you to install it.
+
 No Fortran compiler is needed. Multitaper estimation is implemented natively on
 SciPy's DPSS tapers, so the historical `mtspec` dependency — Fortran source with
 no wheels and no release since 2016 — is no longer required.
@@ -202,6 +224,13 @@ Every output records the configuration that produced it, a hash of it, and the
 SpecMod version, so a locally-overridden run is still reproducible from its
 outputs.
 
+The published Magna results were produced with **0.1.1**, which predates this
+refactor. That code is preserved unchanged on the
+[`master`](https://github.com/sgjholt/SpecMod/tree/master) branch, which is
+protected and frozen; `main` is the trunk now. `0.1.1` was never tagged or
+published to PyPI, so the branch is the reference — there is no release to
+install. Read it there when you need to see exactly what the paper ran.
+
 ## Documentation
 
 The full documentation — the pipeline with its equations, the estimator

{specmod-0.2.0 → specmod-0.2.1}/README.md

@@ -1,5 +1,9 @@
 # SpecMod
 
+[![PyPI](https://img.shields.io/pypi/v/specmod.svg)](https://pypi.org/project/specmod/)
+[![Documentation](https://readthedocs.org/projects/specmod/badge/?version=stable)](https://specmod.readthedocs.io/en/stable/)
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.22071455.svg)](https://doi.org/10.5281/zenodo.22071455)
+
 A Python toolbox for processing and modelling seismic spectra, following the
 method of Edwards *et al.* (2010).
 
@@ -15,26 +19,44 @@ source model to direct-phase spectra.
 > breaking changes at every `0.x` release until the API settles at 1.0 — they
 > land in minor bumps by design, with no deprecation cycle. Pin an exact
 > version for anything you intend to publish.
-> [`docs/roadmap.md`](docs/roadmap.md) says which stages are done and what 1.0
-> will mean; [`docs/REFACTOR_PLAN.md`](docs/REFACTOR_PLAN.md) is the working
-> document behind it.
+> [`docs/roadmap.md`](docs/roadmap.md) says what has shipped, in which version,
+> and what 1.0 will mean; [`docs/REFACTOR_PLAN.md`](docs/REFACTOR_PLAN.md) is
+> the working document behind it.
 
 ## Installation
 
 Requires Python 3.11 or newer.
 
+```sh
+pip install specmod
+```
+
+While this is `0.x`, pin the exact version in anything you intend to publish:
+`pip install specmod==<version>`, taking the current one from the badge above.
+The reason is in the status note — `0.x` releases move names and numbers, and
+the pin plus the configuration stamp each output carries are together what
+make a run reproducible.
+
+To work on SpecMod rather than with it, clone the repository and install it
+editable with the test and lint tooling:
+
 ```sh
 pip install -e ".[dev]"
 ```
 
-Optional extras:
+Optional extras, installable as `pip install "specmod[multitaper]"` or in
+combination — `pip install "specmod[multitaper,wavelet]"`:
 
 | Extra | Adds |
 |---|---|
+| `io` | `h5py` and `pyarrow` — needed to save or load spectra, as HDF5 for arrays and Parquet for tables |
 | `multitaper` | Prieto's `multitaper` package — jackknife confidence intervals, F-test for spectral lines |
 | `wavelet` | PyWavelets, for wavelet families beyond the built-in Morlet |
 | `mcmc` | `emcee`, for Markov-chain Monte Carlo parameter search |
 
+`io` is the one most people want: without it SpecMod computes and plots
+normally, but `specmod.io` raises on the first save telling you to install it.
+
 No Fortran compiler is needed. Multitaper estimation is implemented natively on
 SciPy's DPSS tapers, so the historical `mtspec` dependency — Fortran source with
 no wheels and no release since 2016 — is no longer required.
@@ -146,6 +168,13 @@ Every output records the configuration that produced it, a hash of it, and the
 SpecMod version, so a locally-overridden run is still reproducible from its
 outputs.
 
+The published Magna results were produced with **0.1.1**, which predates this
+refactor. That code is preserved unchanged on the
+[`master`](https://github.com/sgjholt/SpecMod/tree/master) branch, which is
+protected and frozen; `main` is the trunk now. `0.1.1` was never tagged or
+published to PyPI, so the branch is the reference — there is no release to
+install. Read it there when you need to see exactly what the paper ran.
+
 ## Documentation
 
 The full documentation — the pipeline with its equations, the estimator

{specmod-0.2.0 → specmod-0.2.1}/docs/index.md

@@ -24,8 +24,8 @@ treat everything here as provisional until the API settles at 1.0:
 
 What will *not* change silently: the units conventions and the Parseval
 contract are pinned by tests, and the golden references fail loudly rather
-than drifting. The [roadmap](roadmap.md) says which stages are done and what
-1.0 will mean.
+than drifting. The [roadmap](roadmap.md) says what has shipped, in which
+version, and what 1.0 will mean.
 :::
 
 ```python
@@ -67,8 +67,8 @@ print(fits.table[["id", "llpsp", "fc", "ts"]])
   settings that have to be turned on once.
 
 [Roadmap](roadmap.md)
-: What is built, what is being worked on, and what 1.0 will mean. Stages, not
-  dates.
+: What has shipped and in which version, what is being worked on, and what 1.0
+  will mean. Milestones, not dates.
 
 ## Working on SpecMod
 

{specmod-0.2.0 → specmod-0.2.1}/docs/releasing.md

@@ -27,19 +27,52 @@ bump.
 
 ## One-time setup
 
-Five things, none of which can be done from a commit. Until they are done the
+Six things, none of which can be done from a commit. Until they are done the
 release workflow is inert rather than wrong — it opens a release PR and stops.
 
-1. **Let Actions open pull requests.** Settings → Actions → General →
-   Workflow permissions → tick *Allow GitHub Actions to create and approve pull
-   requests*. Without it release-please fails with `GitHub Actions is not
-   permitted to create or approve pull requests`.
-
-2. **Create the `pypi` environment.** Settings → Environments → New
-   environment → `pypi`. Add required reviewers here if you want a second
-   human gate on the upload itself.
+1. **Mint `RELEASE_PLEASE_TOKEN_SPECMOD`.** Settings → Developer settings →
+   Personal access tokens → Fine-grained tokens → *Generate new token*.
 
-3. **Register the trusted publisher on PyPI.** On the project page (or, for
+   | Field | Value |
+   |---|---|
+   | Repository access | Only select repositories → `SpecMod` |
+   | Contents | Read and write |
+   | Pull requests | Read and write |
+   | Expiration | up to 366 days — see the renewal note below |
+
+   Then Settings → Secrets and variables → Actions → *New repository secret*,
+   named exactly `RELEASE_PLEASE_TOKEN_SPECMOD`.
+
+   This is what makes the release PR run CI. Without it the PR is opened by
+   `GITHUB_TOKEN`, which starts no workflow runs at all, so the three required
+   checks never report and the PR is blocked with nothing to fix. The token
+   never touches PyPI — the upload authenticates by OIDC — so this does not
+   reintroduce a publishing secret.
+
+   **It expires.** When it does, the symptom is the old one returning: a
+   release PR with no checks on it. Renew the token and update the secret;
+   nothing in the repository changes. A GitHub App token via
+   `actions/create-github-app-token` avoids the expiry entirely and is the
+   better answer if this becomes annoying.
+
+2. **Let Actions open pull requests.** Settings → Actions → General →
+   Workflow permissions → tick *Allow GitHub Actions to create and approve pull
+   requests*. Only needed as a fallback — with `RELEASE_PLEASE_TOKEN_SPECMOD`
+   set, the PR is opened by a user, not by Actions — but leave it on so the
+   workflow still works if the token lapses.
+
+3. **Create the `pypi` environment.** Settings → Environments → New
+   environment → `pypi`.
+
+   Required reviewers here are optional, and worth thinking about before
+   adding: they hold the `publish` job at `waiting` until a human approves the
+   deployment, and **that approval cannot be given from the GitHub mobile
+   app** — the button exists only on the web UI and the REST API. Merging the
+   release PR is already a deliberate human act, and
+   `tools/check_built_version.py` is what actually prevents a wrong version
+   reaching PyPI, so the reviewer gate buys less than it looks like it does.
+
+4. **Register the trusted publisher on PyPI.** On the project page (or, for
    the first ever upload, under *Publishing* → *Add a new pending publisher*):
 
    | Field | Value |
@@ -53,12 +86,12 @@ release workflow is inert rather than wrong — it opens a release PR and stops.
    that actually runs. If the workflow is ever renamed, this has to be changed
    in the same sitting or the upload fails authentication.
 
-4. **Turn on the Zenodo webhook.** Log into Zenodo with GitHub, find `SpecMod`
+5. **Turn on the Zenodo webhook.** Log into Zenodo with GitHub, find `SpecMod`
    in the repository list, and flip the switch. It takes effect for releases
    made *after* it is on, so do it before the first release rather than after.
    `CITATION.cff` supplies the metadata.
 
-5. **Require the checks on `main`.** Branch protection → *Require status
+6. **Require the checks on `main`.** Branch protection → *Require status
    checks to pass* → add exactly three: **`ci`**, **`docs`**, **`build`**.
 
    Those are job names, not workflow names, and only these three are stable:
@@ -68,10 +101,12 @@ release workflow is inert rather than wrong — it opens a release PR and stops.
    instead matches nothing, and a required check that never reports blocks
    every merge.
 
-   The release pull request is an ordinary pull request and goes through them
-   like any other — including the approval step, since GitHub holds workflow
-   runs on pull requests opened by `github-actions[bot]` until a maintainer
-   approves them.
+   The release pull request goes through them like any other — but only
+   because of step 1. This page previously said GitHub *holds* the runs on a
+   `github-actions[bot]` pull request until a maintainer approves them, and
+   that is not what happens: no runs are created, there is nothing to approve,
+   and the PR sits blocked with an empty check list.
+   `RELEASE_PLEASE_TOKEN_SPECMOD` is what makes this paragraph true.
 
 ## What a version number means while this is 0.x
 
@@ -108,13 +143,20 @@ To skip a release, do not merge the PR. It stays open and keeps accruing.
 ## Things that are the way they are for a reason
 
 **The publish job is in `release.yml`, not a separate `publish.yml`.** The
-obvious design — a workflow keyed on `release: published` — never fires.
-release-please creates the release with the default `GITHUB_TOKEN`, and
-"events triggered by the `GITHUB_TOKEN` will not create a new workflow run".
-The workaround is a personal access token in secrets, which is the one thing
-Trusted Publishing exists to avoid, so the publish job gates on
-release-please's own `release_created` output instead. Zenodo is unaffected:
-it listens to the release *webhook*, which is not subject to that restriction.
+obvious design — a workflow keyed on `release: published` — could not fire at
+all when release-please ran on the default `GITHUB_TOKEN`, because "events
+triggered by the `GITHUB_TOKEN` will not create a new workflow run". So the
+publish job gates on release-please's own `release_created` output instead.
+
+`RELEASE_PLEASE_TOKEN_SPECMOD` removes that constraint — a release created by
+a PAT *does* start workflow runs — so a separate `publish.yml` would now work.
+It is still not worth splitting: one workflow means one `concurrency` group, one
+place to read, and no dependency on the ordering of two runs that would race
+whenever two merges land together. The `release_created` gate is also exact,
+where an event key would fire on any release including one made by hand.
+
+Zenodo was never affected either way: it listens to the release *webhook*,
+which is not subject to the token restriction.
 
 **`include-component-in-tag` is `false`.** Left on, the tag is
 `specmod-v0.2.0`, which `pyproject.toml`'s `--match v[0-9]*` does not describe
@@ -165,3 +207,18 @@ If the `publish` job fails after the release exists — a transient PyPI error,
 say — re-run that job from the Actions UI. Do not re-run `release-please`
 expecting a second attempt: `release_created` is only true on the run that
 created the release.
+
+## When the release PR has no checks on it
+
+Not a red check — *no checks at all*, an empty list, and the PR blocked
+because the three required ones never reported. This means release-please fell
+back to `GITHUB_TOKEN`: either `RELEASE_PLEASE_TOKEN_SPECMOD` is unset, or it
+expired, or its repository access no longer covers `SpecMod`. Renew it
+(one-time setup, step 1); nothing in the repository needs changing.
+
+To unblock the release PR that is already open, without waiting for a new
+commit: **close it and immediately reopen it.** That re-fires
+`pull_request.reopened` from your account rather than from the token, and the
+checks run. It is the same trick that got `v0.2.0` out, and it is safe — the
+`autorelease: pending` label survives, so release-please still recognises the
+merge as a release, and no history is touched.

specmod-0.2.1/docs/roadmap.md

@@ -0,0 +1,148 @@
+# Roadmap
+
+SpecMod is being rebuilt in stages, each one independently usable. This page
+says what has shipped, in which version, what is being worked on, and what 1.0
+will mean.
+
+**No dates.** The order is by dependency, not by calendar, and what comes after
+the current milestone can still change. Shipped work names the version that
+carries it, so it can be installed and checked rather than taken on trust;
+unreleased work says so plainly.
+[`REFACTOR_PLAN.md`](https://github.com/sgjholt/SpecMod/blob/main/docs/REFACTOR_PLAN.md)
+is the working document behind this one and carries the reasoning, the
+measurements and the open questions.
+
+## Where it is now
+
+**v0.2.0**, the first release of the rebuilt package —
+[on PyPI](https://pypi.org/p/specmod), with a Zenodo DOI and its own
+[documentation version](https://specmod.readthedocs.io/en/stable/). Install it
+with `pip install specmod`.
+
+Still alpha, still pre-1.0: names and signatures move between `0.x` releases
+without a deprecation cycle. Everything below marked shipped is released,
+tested against golden references, and usable — but pin an exact version for
+anything you intend to publish. See
+[Releasing the software](releasing.md) for what a version number means here.
+
+## Shipped in v0.2.0
+
+The version before this one, `0.1.1`, is the pre-refactor code that produced
+the published Magna results. It is preserved unchanged on the
+[`master`](https://github.com/sgjholt/SpecMod/tree/master) branch, which is
+protected and frozen — it was never tagged or published to PyPI, so that
+branch is the only reference to it. Everything below is the delta between it
+and v0.2.0, which is why the first changelog is enormous and correctly so.
+
+### An installable package
+
+A real `pyproject.toml`, `src/` layout, snake_case modules, linting, type
+checking and a test suite on CI. Before this, the package could not be
+installed or imported without editing paths by hand.
+
+### Configuration without globals
+
+Settings live in a `config/` package with semantic sections and layered
+overrides, instead of module-level constants read at import time. Every output
+records the configuration that produced it, so a locally-overridden run is
+reproducible from its own outputs.
+
+### Publishing: docs, PyPI, DOI
+
+This site, built from the repository on every merge; automated changelog and
+version derivation from tags; PyPI upload through Trusted Publishing; a Zenodo
+DOI per release. Deliberately built early, while the package was small enough
+that debugging the pipeline was cheap — and v0.2.0 is the release that proved
+every leg of it end to end.
+
+A fresh clone still needs the one-time repository settings listed in
+[Releasing the software](releasing.md); they are account and repository state,
+not something a commit can carry.
+
+### The transform layer
+
+One `SpectralEstimator` protocol with interchangeable implementations —
+`FFTEstimator`, `WelchEstimator`, `MultitaperEstimator` and Prieto's — plus
+Konno–Ohmachi smoothing and log-binning as separate, composable steps. The
+`mtspec` Fortran dependency, which no longer builds on current toolchains, is
+demoted to an optional legacy backend rather than being the only path.
+
+What each estimator does to real data is measured in
+[Choosing a transform](choosing-a-transform.md); the differences are large
+enough to matter to a magnitude.
+
+### Wavelets
+
+A continuous wavelet transform alongside the Fourier estimators:
+`CWTEstimator`, a `Scalogram` that tracks its cone of influence, quality
+checks over it, and time-averaging back to a spectrum with ground-motion units
+preserved.
+
+### Typed, portable persistence
+
+HDF5 for arrays and Parquet for tables, replacing pickle everywhere — nothing
+in the package can write a pickle any more, so a saved result is readable
+without the code that wrote it and cannot execute anything on load.
+
+### A stable import surface
+
+`specmod.api` — a path-free, deterministic, non-mutating import surface with
+typed errors, for downstream packages that need something narrower than the
+whole package and less volatile than its internals.
+
+## In progress — not yet released
+
+### Finishing the decomposition
+
+Breaking the remaining large modules into packages with narrow
+responsibilities. The spectral core, the fitting layer and the pick readers
+are already packages, and the type-checking backlog is empty.
+
+What is left: `io.py` and `plotting.py` are still single modules, and the
+operations that mutate in place need to return new objects instead. Neither is
+large — the split is about responsibilities, not line count.
+
+## Planned
+
+### 1.0 — the API stops moving
+
+The theory page that states the normalisation and units conventions
+explicitly, the tutorial rebuilt as an executed notebook so it cannot rot
+silently, and a "what changed since 0.1" guide for anyone upgrading. Then the
+1.0 release, which is the promise that names and signatures stop moving
+without a deprecation cycle.
+
+That promise is the whole content of the number, which is why it has to be a
+decision rather than something a breaking commit does on its way past. Until
+it is made, breaking changes bump the minor.
+
+## After 1.0
+
+Designed but deliberately not on the path to 1.0, because each is blocked on
+an input rather than on effort — mostly a real file from a real tool, which a
+guess written from documentation cannot substitute for:
+
+- **Presets for picker output** (PhaseNet, EQTransformer, SeisBench), so those
+  users write no column mapping. The configurable reader already exists; a
+  preset is a mapping and a test against one real file.
+- **Confirming two more pick formats** (NonLinLoc `.hyp`, IMS/GSE bulletins)
+  that cannot be round-tripped through ObsPy and so are listed as unconfirmed
+  rather than claimed.
+- **SeisComP picks**, which ObsPy's SCML reader currently discards. A test
+  fails when that starts working upstream.
+- **Recording pick-resolution policy in the configuration**, alongside the
+  provenance stamp.
+- **A fuller `acquire --verify`** that re-fetches and diffs against the
+  manifest, rather than only detecting local tampering.
+
+## How this page works
+
+Each shipped entry names the version that carries it, so a reader can install
+that version and check the claim. Work that is merged but unreleased sits under
+*In progress* and gets its version when a release goes out — merged is not
+shipped, and this page does not blur the two.
+
+Before v0.2.0 this was a list of stages, because there was no released version
+to point at and "done" could only mean merged. The full changelog for every
+release is in
+[`CHANGELOG.md`](https://github.com/sgjholt/SpecMod/blob/main/CHANGELOG.md).

specmod-0.2.0/.release-please-manifest.json

@@ -1,3 +0,0 @@
-{
-  ".": "0.2.0"
-}