anchortest 0.1.0__tar.gz

anchortest-0.1.0/.github/FUNDING.yml

@@ -0,0 +1,8 @@
+# GitHub Sponsors / funding links for this repo.
+# REPLACE-ME placeholders below before this takes effect -- GitHub ignores unset fields, but a literal
+# "REPLACE-ME" left in place will show a broken link. Fill in only the ones you actually set up:
+#   - github: your GitHub username, after enabling GitHub Sponsors on your account (Settings > Sponsors)
+#   - custom: a list of URLs (e.g. a Gumroad or Stripe Payment Link page), if you set one up
+
+github: REPLACE-ME
+# custom: ["https://REPLACE-ME"]

anchortest-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,21 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.9", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[dev]"
+      - run: python -m unittest discover -s tests
+      - run: python tests/mutation_check.py
+      - run: python examples/random_walk_example.py

anchortest-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,50 @@
+name: Publish to PyPI
+
+# Runs when you publish a GitHub Release. Uses PyPI's Trusted Publishing (OIDC) -- no API token stored
+# anywhere, in this repo or on PyPI. One-time setup required on PyPI's side; see RELEASING.md.
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - run: pip install -e ".[dev]"
+      - run: python -m unittest discover -s tests
+      - run: python tests/mutation_check.py
+
+  build:
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - run: pip install build
+      - run: python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write   # required for OIDC trusted publishing -- this is the only credential involved
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

anchortest-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.pyc
+.pytest_cache/
+.venv/
+dist/
+build/
+*.egg-info/
+.DS_Store

anchortest-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Grant Miller
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

anchortest-0.1.0/MANIFESTO.md

@@ -0,0 +1,110 @@
+# Your backtest is lying to you, and it's not the bug you're looking for
+
+Every backtester knows to check for lookahead bias. Fewer check for the three things below — because each
+one produces a result that looks completely honest. The code runs. The number is real. The chart is
+plausible. And it's still wrong, in a way that a normal test suite and a normal code review will not catch.
+
+These are three real incidents from one live quant-research project. All three shipped — became "confirmed"
+results the project acted on — before something caught them.
+
+## 1. The single-anchor illusion
+
+A covered-call strategy rebalanced every 30 trading days. Its backtest picked rebalance dates the obvious
+way: every 30th day, starting from the first day of data. Nobody thought twice about that "first day of
+data" choice — it's just where the data starts.
+
+Except it isn't a neutral choice. It's a phase. Shift the starting point by a single trading day and you get
+a genuinely different, non-overlapping sequence of ~120 entry and exit dates across a decade of data — not
+noise around a stable number, a different simulation.
+
+Someone eventually swept all 30 possible phases of that 30-day cycle. Sharpe ranged from 0.35 to 1.46. And
+the one phase every prior test had used — the "obvious" one, day zero — was the single best of all 30.
+
+Every parameter decision the project had made up to that point had been validated against the luckiest
+number available, not a representative one. Nobody had cherry-picked it on purpose. The backtest had
+cherry-picked it for them, silently, the moment someone wrote `data[::30]` instead of thinking about what
+that slice actually meant.
+
+**The fix is almost insultingly simple: run every phase, not one.** The hard part is remembering to, every
+single time, on every candidate, forever — which is the actual reason to put it in a library instead of a
+habit.
+
+## 2. The bug that only breaks in one direction
+
+Drawdown is naturally a negative number. A 20% drawdown is `-0.20`; a worse, 30% drawdown is `-0.30`. That's
+correct and everyone knows it. It's also exactly the setup for a comparison bug that only breaks in the
+direction that makes you happy.
+
+Write the comparison the way it reads in English — "is the candidate's drawdown at least as good as the
+baseline's?" — and you get `candidate_dd <= baseline_dd`. Plug in the numbers: `-0.30 <= -0.20` is `True`.
+The candidate with the DEEPER, WORSE drawdown just passed the check.
+
+This shipped. Three separate candidates were reported as "confirmed improvements — every metric passed" on
+this exact line of code, before someone doing an unrelated manual double-check noticed the numbers didn't
+smell right and traced it back.
+
+The bug is one character's worth of intent, encoded in a symbol (`<=`) that means something different than
+it looks like it means once you remember which way the number is stored. Nobody writing that line was
+careless. The line just doesn't say what it looks like it says.
+
+**The fix, again, is simple — get the direction right once, in one function everyone calls, and never let
+anyone write the comparison inline again.** The value isn't the fix. It's that the fix has to exist
+somewhere other than "be careful," because "be careful" already failed three times.
+
+## 3. The result that was better on a strategy with no strategy in it
+
+This is the one that should worry you most, because it doesn't look like a bug. It looks like a genuine,
+exciting result.
+
+The idea: split one strategy into several "tranches," each running the same logic but offset by a few days,
+then blend them — average tranche 1's cycle-7 return with tranche 2's cycle-7 return, and so on — the way
+you'd diversify a portfolio across managers who trade slightly out of phase with each other.
+
+It looked fantastic. Sharpe up 27%. Drawdown several points shallower. A real, structural improvement, the
+kind you build a new version of your strategy around.
+
+Someone ran the control before believing it: apply the *exact same blending code* to plain buy-and-hold. Buy
+plain SPY, do nothing else, blend it the same way. Buy-and-hold cannot possibly have any real "phase skill"
+to capture — there's no strategy in it, just a price series. It "improved" by almost the same ratio. Sharpe
+0.89 to 1.20, on doing literally nothing, blended.
+
+What was actually happening: averaging several time-shifted windows smooths out variance across those
+windows. It's a low-pass filter on noise, dressed up in returns notation. It has nothing to do with skill,
+diversification, or risk reduction — it would have "worked" on a coin flip. If that one control run hadn't
+happened, that result would have shipped as the project's best-ever finding.
+
+**The generalizable lesson: if a technique can only be validated by looking at the strategy, it hasn't been
+validated.** Construct the version where you know the honest answer in advance — a control, a null model, a
+strategy-free baseline — and run your technique against *that* first. If it "wins" there too, you've found
+an artifact, not an edge.
+
+---
+
+## Why these three, and not a list of forty
+
+They're not exotic. None involves a subtle statistics error or a rare edge case in floating-point math.
+They're the kind of mistake that survives a working code review, survives `git blame`, survives a green test
+suite — because in each case, the code did exactly what it was written to do. The bug was in what it was
+written to *mean*.
+
+That's the actual argument for packaging these as automated checks instead of a mental checklist: a mental
+checklist degrades every time you're tired, in a hurry, or excited about a number that finally looks good.
+A function that runs anyway doesn't.
+
+## What we built
+
+**[AnchorTest](https://github.com/grant02339-ship-it/anchortest)** is the smallest library that runs these three
+checks by default: anchor-average instead of trusting one phase, compare with the sign convention fixed in
+one place, and check any blending logic against a phase-invariant control before trusting it. Plus a small
+mutation-testing helper, because "we have tests" is a claim that deserves its own falsification check.
+
+It's free, it's MIT-licensed, and it's about 400 lines of code — on purpose. The value isn't the amount of
+code. It's that these three specific mistakes, having already cost one project real time and nearly cost it
+a shipped false result, don't get to cost you the same thing.
+
+```bash
+pip install -e .   # from the repo, until it's on PyPI
+```
+
+If you've got your own war story — a result that looked right until you ran the control that wasn't obvious
+to run — that's the kind of issue or PR this project wants most.

anchortest-0.1.0/PKG-INFO

@@ -0,0 +1,152 @@
+Metadata-Version: 2.5
+Name: anchortest
+Version: 0.1.0
+Summary: Stop trusting a single backtest run: anchor-average across every phase of your cycle, compare candidates without the drawdown sign trap, and catch blending artifacts before you ship a strategy.
+Project-URL: Homepage, https://github.com/grant02339-ship-it/anchortest
+Project-URL: Repository, https://github.com/grant02339-ship-it/anchortest
+Author-email: grant02339@gmail.com
+License-Expression: MIT
+License-File: LICENSE
+Keywords: backtesting,finance,overfitting,quant,trading,validation
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Requires-Python: >=3.9
+Requires-Dist: numpy>=1.24
+Requires-Dist: pandas>=2.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# AnchorTest
+
+**Stop trusting a single backtest run.**
+
+Most backtests report one run's Sharpe ratio, on one start date, over one universe. That number is a sample
+of one. AnchorTest is a small, dependency-light Python library (`numpy` + `pandas`, nothing else) that runs
+three specific checks that have each caught a real, shipped bug in real trading-strategy research:
+
+1. **Anchor-average**, instead of trusting one lucky start date.
+2. **Compare candidates correctly**, with the drawdown sign-convention trap fixed once, in one place.
+3. **Catch a blending/tranching artifact** before it becomes your headline result.
+
+Plus a small, general-purpose **mutation-testing helper**, because a green test suite doesn't tell you it
+would have caught the bug you didn't think to write a test for.
+
+## Why this exists
+
+Three real incidents from one live quant-research project, each of which shipped before it was caught:
+
+> **1. A single-anchor backtest is a sample of one.** A strategy's backtest struck rebalance dates as a
+> fixed stride starting from wherever the data happened to begin. Sweeping every possible phase of a 30-day
+> cycle found Sharpe ranging from 0.35 to 1.46 -- and the ONE phase every earlier test had used happened to
+> land on literally the best of all 30. Every parameter decision made before this was caught had been
+> validated against the luckiest possible number, not a representative one.
+
+> **2. A sign-convention bug that shipped three false wins.** Drawdown is naturally stored as a negative
+> number (a shallower, better drawdown is closer to zero). A comparison written the obvious way --
+> `candidate_dd <= baseline_dd` -- silently treats a DEEPER, WORSE drawdown as a pass, because `-0.30 <=
+> -0.20` is true. Three candidates were reported as "confirmed improvements" on this exact bug before a
+> manual re-check caught it.
+
+> **3. A blending result that was pure measurement artifact.** Averaging several phase-shifted copies of a
+> strategy (offset "tranches") by taking the mean of cycle-i's return across all of them looked like a
+> genuine diversification win: Sharpe up 27%, drawdown several points shallower. The check that caught it:
+> running the IDENTICAL blend on plain buy-and-hold, which cannot have any real phase-dependent skill by
+> construction. Buy-and-hold "improved" by almost the same ratio (Sharpe 0.89 -> 1.20). The blend was
+> smoothing variance across offset windows, not reducing real risk -- and it would have shipped as the
+> project's best result if that one control hadn't been run.
+
+None of these are exotic mistakes. They're the kind of thing that survives code review, survives a
+reasonable test suite, and looks exactly like a genuine result until someone runs the specific control that
+exposes it. AnchorTest packages those controls so you run them by default, not by luck.
+
+## Install
+
+```bash
+pip install anchortest    # once published -- see below
+# or, for now:
+pip install -e .
+```
+
+Requires Python 3.9+, `numpy`, `pandas`. No `scipy`, no broker SDK, no options-pricing library -- this works
+on any equity-curve-producing backtest, in any asset class, options or not.
+
+## Paid audits
+
+I'll run these checks against YOUR backtest and send back a written report: what passed, what didn't, and
+why. **Quick Check ($199, 3 business days):** anchor-average your existing backtest, run it against the
+strict bar, check any blending logic for the artifact pattern above. **Full Audit ($749, 7 business days):**
+Quick Check plus a held-out/out-of-sample test designed for your specific strategy, plus a 30-minute call.
+This is a review of your validation process, not investment advice and not a claim that any strategy is
+profitable. Email grant02339@gmail.com to book, or see the landing page (`docs/index.html`).
+
+## Quickstart
+
+```python
+from anchortest import anchor_average, compare, clears_bar
+
+def backtest(params, start_shift=0):
+    """Your own backtest. MUST accept start_shift and drop that many rows of your underlying
+    price data before computing anything -- see examples/random_walk_example.py for a full one."""
+    ...  # returns a pandas Series equity curve, indexed by date, starting at 1.0
+
+baseline, _ = anchor_average(backtest, baseline_params, cycle_days=25, n_anchors=25)
+candidate, _ = anchor_average(backtest, candidate_params, cycle_days=25, n_anchors=25)
+
+delta = compare(baseline, candidate)
+if clears_bar(delta):
+    print("candidate improves EVERY tracked metric -- worth a closer look")
+else:
+    print("not a promotion:", delta)
+```
+
+Run `python examples/random_walk_example.py` for a runnable end-to-end demo, including a case where the
+single-anchor (`shift=0`) result actively disagrees with the honest average.
+
+## What's in the box
+
+| function | catches |
+|---|---|
+| `anchor_average(backtest_fn, params, cycle_days, n_anchors=25)` | trusting one lucky start date |
+| `shifts_for(cycle_days, n_anchors)` | the phase-shift arithmetic itself (deduplicates correctly when `n_anchors > cycle_days`) |
+| `compare(baseline, candidate)` / `clears_bar(delta)` | the drawdown sign-convention trap; "5 of 6 metrics improved" being reported as a win |
+| `check_blend_artifact(blend_fn)` / `assert_no_blend_artifact(result)` | a tranching/blending function that inflates Sharpe with no real skill |
+| `run_mutation_suite(mutations, test_command)` / `assert_all_caught(results)` | a test suite that would not actually have caught the bug you just fixed |
+
+Each function's docstring explains the real failure mode it generalizes from -- read them; the "why" is not
+padding.
+
+## Philosophy
+
+- **Compare against a control before you trust a transform.** If you can construct a version of your data
+  where the "true" answer is known (a phase-invariant control, a random baseline, a null model), run your
+  method against it before running it on the real thing. `check_blend_artifact` is one instance of this
+  principle; it generalizes further than this library currently automates.
+- **The strict bar exists because partial improvement has been about a coin flip.** A candidate that
+  improves mean Sharpe while its minimum-case Sharpe or recent-half Sharpe gets worse is not free money --
+  in real testing, that exact pattern has predicted a real-world regression as often as an improvement.
+  `clears_bar`'s default requires every tracked metric to improve, deliberately.
+- **A green test suite is a claim, not a fact, until you've tried to falsify it.** `run_mutation_suite` is
+  the smallest possible version of "did this test actually assert anything, or did it just not crash."
+
+## What this is not
+
+- Not a backtesting engine. Bring your own `backtest_fn`; AnchorTest only tells you how much to trust its
+  output.
+- Not investment advice, and not a signal that any particular strategy works. It's a set of falsification
+  checks -- what survives them still needs real out-of-sample and (if it trades real markets) real
+  historical-data testing before anyone should trust it with money.
+- Not a substitute for testing out-of-sample, on assets or time periods you didn't tune on. That discipline
+  matters at least as much as anything in this library automates; there's no shortcut for it here yet.
+
+## Contributing
+
+Issues and PRs welcome, especially: additional artifact-detection controls, a walk-forward /
+purged-cross-validation helper, and real-world "this caught a bug" case studies to add to the list above.
+
+## License
+
+MIT. See `LICENSE`.

anchortest-0.1.0/README.md

@@ -0,0 +1,130 @@
+# AnchorTest
+
+**Stop trusting a single backtest run.**
+
+Most backtests report one run's Sharpe ratio, on one start date, over one universe. That number is a sample
+of one. AnchorTest is a small, dependency-light Python library (`numpy` + `pandas`, nothing else) that runs
+three specific checks that have each caught a real, shipped bug in real trading-strategy research:
+
+1. **Anchor-average**, instead of trusting one lucky start date.
+2. **Compare candidates correctly**, with the drawdown sign-convention trap fixed once, in one place.
+3. **Catch a blending/tranching artifact** before it becomes your headline result.
+
+Plus a small, general-purpose **mutation-testing helper**, because a green test suite doesn't tell you it
+would have caught the bug you didn't think to write a test for.
+
+## Why this exists
+
+Three real incidents from one live quant-research project, each of which shipped before it was caught:
+
+> **1. A single-anchor backtest is a sample of one.** A strategy's backtest struck rebalance dates as a
+> fixed stride starting from wherever the data happened to begin. Sweeping every possible phase of a 30-day
+> cycle found Sharpe ranging from 0.35 to 1.46 -- and the ONE phase every earlier test had used happened to
+> land on literally the best of all 30. Every parameter decision made before this was caught had been
+> validated against the luckiest possible number, not a representative one.
+
+> **2. A sign-convention bug that shipped three false wins.** Drawdown is naturally stored as a negative
+> number (a shallower, better drawdown is closer to zero). A comparison written the obvious way --
+> `candidate_dd <= baseline_dd` -- silently treats a DEEPER, WORSE drawdown as a pass, because `-0.30 <=
+> -0.20` is true. Three candidates were reported as "confirmed improvements" on this exact bug before a
+> manual re-check caught it.
+
+> **3. A blending result that was pure measurement artifact.** Averaging several phase-shifted copies of a
+> strategy (offset "tranches") by taking the mean of cycle-i's return across all of them looked like a
+> genuine diversification win: Sharpe up 27%, drawdown several points shallower. The check that caught it:
+> running the IDENTICAL blend on plain buy-and-hold, which cannot have any real phase-dependent skill by
+> construction. Buy-and-hold "improved" by almost the same ratio (Sharpe 0.89 -> 1.20). The blend was
+> smoothing variance across offset windows, not reducing real risk -- and it would have shipped as the
+> project's best result if that one control hadn't been run.
+
+None of these are exotic mistakes. They're the kind of thing that survives code review, survives a
+reasonable test suite, and looks exactly like a genuine result until someone runs the specific control that
+exposes it. AnchorTest packages those controls so you run them by default, not by luck.
+
+## Install
+
+```bash
+pip install anchortest    # once published -- see below
+# or, for now:
+pip install -e .
+```
+
+Requires Python 3.9+, `numpy`, `pandas`. No `scipy`, no broker SDK, no options-pricing library -- this works
+on any equity-curve-producing backtest, in any asset class, options or not.
+
+## Paid audits
+
+I'll run these checks against YOUR backtest and send back a written report: what passed, what didn't, and
+why. **Quick Check ($199, 3 business days):** anchor-average your existing backtest, run it against the
+strict bar, check any blending logic for the artifact pattern above. **Full Audit ($749, 7 business days):**
+Quick Check plus a held-out/out-of-sample test designed for your specific strategy, plus a 30-minute call.
+This is a review of your validation process, not investment advice and not a claim that any strategy is
+profitable. Email grant02339@gmail.com to book, or see the landing page (`docs/index.html`).
+
+## Quickstart
+
+```python
+from anchortest import anchor_average, compare, clears_bar
+
+def backtest(params, start_shift=0):
+    """Your own backtest. MUST accept start_shift and drop that many rows of your underlying
+    price data before computing anything -- see examples/random_walk_example.py for a full one."""
+    ...  # returns a pandas Series equity curve, indexed by date, starting at 1.0
+
+baseline, _ = anchor_average(backtest, baseline_params, cycle_days=25, n_anchors=25)
+candidate, _ = anchor_average(backtest, candidate_params, cycle_days=25, n_anchors=25)
+
+delta = compare(baseline, candidate)
+if clears_bar(delta):
+    print("candidate improves EVERY tracked metric -- worth a closer look")
+else:
+    print("not a promotion:", delta)
+```
+
+Run `python examples/random_walk_example.py` for a runnable end-to-end demo, including a case where the
+single-anchor (`shift=0`) result actively disagrees with the honest average.
+
+## What's in the box
+
+| function | catches |
+|---|---|
+| `anchor_average(backtest_fn, params, cycle_days, n_anchors=25)` | trusting one lucky start date |
+| `shifts_for(cycle_days, n_anchors)` | the phase-shift arithmetic itself (deduplicates correctly when `n_anchors > cycle_days`) |
+| `compare(baseline, candidate)` / `clears_bar(delta)` | the drawdown sign-convention trap; "5 of 6 metrics improved" being reported as a win |
+| `check_blend_artifact(blend_fn)` / `assert_no_blend_artifact(result)` | a tranching/blending function that inflates Sharpe with no real skill |
+| `run_mutation_suite(mutations, test_command)` / `assert_all_caught(results)` | a test suite that would not actually have caught the bug you just fixed |
+
+Each function's docstring explains the real failure mode it generalizes from -- read them; the "why" is not
+padding.
+
+## Philosophy
+
+- **Compare against a control before you trust a transform.** If you can construct a version of your data
+  where the "true" answer is known (a phase-invariant control, a random baseline, a null model), run your
+  method against it before running it on the real thing. `check_blend_artifact` is one instance of this
+  principle; it generalizes further than this library currently automates.
+- **The strict bar exists because partial improvement has been about a coin flip.** A candidate that
+  improves mean Sharpe while its minimum-case Sharpe or recent-half Sharpe gets worse is not free money --
+  in real testing, that exact pattern has predicted a real-world regression as often as an improvement.
+  `clears_bar`'s default requires every tracked metric to improve, deliberately.
+- **A green test suite is a claim, not a fact, until you've tried to falsify it.** `run_mutation_suite` is
+  the smallest possible version of "did this test actually assert anything, or did it just not crash."
+
+## What this is not
+
+- Not a backtesting engine. Bring your own `backtest_fn`; AnchorTest only tells you how much to trust its
+  output.
+- Not investment advice, and not a signal that any particular strategy works. It's a set of falsification
+  checks -- what survives them still needs real out-of-sample and (if it trades real markets) real
+  historical-data testing before anyone should trust it with money.
+- Not a substitute for testing out-of-sample, on assets or time periods you didn't tune on. That discipline
+  matters at least as much as anything in this library automates; there's no shortcut for it here yet.
+
+## Contributing
+
+Issues and PRs welcome, especially: additional artifact-detection controls, a walk-forward /
+purged-cross-validation helper, and real-world "this caught a bug" case studies to add to the list above.
+
+## License
+
+MIT. See `LICENSE`.

anchortest-0.1.0/RELEASING.md

@@ -0,0 +1,46 @@
+# Releasing
+
+Publishing uses PyPI's **Trusted Publishing** (OIDC): GitHub proves its identity to PyPI at publish time,
+so no API token is ever stored in this repo, in a GitHub secret, or anywhere else. `.github/workflows/publish.yml`
+already does the automated half; the parts below need a human with a PyPI account.
+
+## One-time setup (do this once, before the first release)
+
+1. Create a PyPI account at [pypi.org/account/register](https://pypi.org/account/register/), if you don't
+   have one. Enable 2FA -- PyPI requires it for publishing.
+2. Go to [pypi.org/manage/account/publishing](https://pypi.org/manage/account/publishing/) and add a
+   **pending publisher** (this works even though the `anchortest` project doesn't exist on PyPI yet):
+   - PyPI project name: `anchortest`
+   - Owner: `grant02339-ship-it`
+   - Repository name: `anchortest`
+   - Workflow name: `publish.yml`
+   - Environment name: `pypi`
+3. That's it -- no token to copy anywhere. The first successful run of the `publish` job creates the
+   project on PyPI automatically.
+
+## Cutting a release (every time after that)
+
+```bash
+cd ~/anchortest
+# 1. bump the version
+sed -i '' 's/version = "0.1.0"/version = "0.1.1"/' pyproject.toml   # pick the real next version
+git add pyproject.toml
+git commit -m "Bump version to 0.1.1"
+git push
+
+# 2. tag and create a GitHub Release -- this is what triggers publish.yml
+git tag v0.1.1
+git push origin v0.1.1
+gh release create v0.1.1 --title "v0.1.1" --generate-notes
+```
+
+`gh release create` triggers the `release: published` event, which runs the full pipeline: tests +
+mutation check, build, then publish to PyPI. Watch it with `gh run watch` or at
+`https://github.com/grant02339-ship-it/anchortest/actions`.
+
+## Sanity check after the first publish
+
+```bash
+pip install anchortest
+python -c "import anchortest; print(anchortest.__version__)"
+```