docs: the changelog gets a directory, and a session gets a version

Two conventions, written down where each is enforced rather than remembered.

**`changelog/`, one file per major line.** A single growing file is the thing this
avoids: a reader should open `1.x.md` and find their version without scrolling past
releases they do not care about. Root `CHANGELOG.md` is a pointer, because two places to
write a release note is one place to forget.

A pre-release line gets its **own** file, named for the line it leads to, and is not
folded in when that line goes stable — the beta file is what says *when* a behaviour
changed during the run-up, and merging it would double the length of the file people
actually read while losing exactly that.

The split rule is stated in terms of **reading length rather than release count**, since
that is the property being defended: past roughly 600 lines, split into contiguous minor
ranges and leave the old name as a stub so no link breaks. Range files are never
renumbered — `1.0-1.4.md` does not become `1.0-1.6.md` at the next split.

Entries are backfilled for 1.0.0, 1.1.0 and 1.2.0, written for a *user*: what changed,
what they have to do about it, and — for 1.2.0 — that the legal gate will appear once,
which is the kind of thing a release note exists to say before someone reports it as a
bug. Deliberately no commit counts: a number written about the repository inside the
repository goes stale on commit, which AI-DISCLOSURE learned three times.

**One session, one slice, one version.** Depth over breadth, plus a hotfix release when
one is needed. It is in CLAUDE.md's conventions because that is what the next session
reads first.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
poli0981andClaude Opus 5 committed 2026-08-18 12:07:57 +07:00
1 parent 99a25f3fa4
commit 39a0c54f05
4 files changed
+153

No files matched your search

+9
View File
@@ -0,0 +1,9 @@
# Changelog
Kept in [`changelog/`](changelog/), one file per major line, newest release first.
- **[1.x](changelog/1.x.md)** — 1.0.0 onward
- [Conventions and the split rule](changelog/README.md)
This file is a pointer, not a copy. A single growing changelog is the thing the directory exists to
avoid, and two places to write a release note is one place to forget.
+9
View File
@@ -49,6 +49,15 @@ failed package never aborts a batch (skip-and-continue, then a `"13 successful,
## Conventions
- **One session, one slice, one version.** A session takes a single item — a `docs/ROADMAP.md`
entry, or something that surfaced while doing one — takes it *deep*, tests it properly, and ships
it as one version, plus a patch release if it needs a hotfix. Not several shallow items. The
record of what a slice cost goes in ROADMAP; what a *user* would notice goes in `changelog/`.
- **The changelog lives in `changelog/`, one file per major line** (`1.x.md`), with a pre-release
line getting its own file (`2.0-beta.md`). Root `CHANGELOG.md` is a pointer only. Split a file by
minor range at roughly 600 lines and never renumber an existing range file —
`changelog/README.md` is the authority.
- Crates `pipdock-*`; React components prefixed `Pd` (`PdPackageRow`, `PdConflictDialog`)
- Tauri identifier `com.skullmute.pipdock`; CLI binary `pipdock`
- Frontend lives in `ui/`, but `package.json` sits at the **repo root** so the ops-repo
+85
View File
@@ -0,0 +1,85 @@
# 1.x
Newest first. See [`README.md`](README.md) for the conventions, and `docs/ROADMAP.md` for what each
slice cost and what it taught — that is a different document for a different reader.
## 1.2.0 — 2026-08-18
The **Security tab**, which the sidebar has shown greyed out since M2.
### Added
- **Security (`Ctrl+7`)** — known advisories against the packages installed in the selected
environment, grouped by package. Each carries its id, the versions that fix it, its other ids
(which is where the CVE is), the advisory text, and a link to its entry on osv.dev.
- **Cancel**, because an audit takes 18–68 seconds — the first one longer, since it builds its own
tool environment.
- **Save report…**, writing Markdown and JSON beside a path you choose, as Code Health already did.
- `pipdock audit` at the command line. **Exit 1 when it finds something**, 0 when it does not, so a
script can branch on it.
- The Security tool environment is now listed in Settings → disk usage, and can be cleared there.
### Changed
- **There is no severity column, and there was never going to be one.** The documentation promised
findings sorted by severity; pip-audit publishes no severity at all. Findings are ordered by
package, then by whether anything *fixes* them, then by id — the distinction that changes what you
can do about one. PipDock does not invent a number to put in the gap.
- Advisories come from **PyPI's** advisory data. PipDock still connects to nothing but pypi.org;
the osv.dev link is your browser going there after you click it.
### You will see this once
**The first-run legal screen appears again.** The licence, disclaimer and third-party notices all
described pip-audit as planned and not yet used, and that stopped being true. Your acceptance is
recorded against the documents' version, so a change to them asks once more. Nothing else resets.
### Fixed
- The update preview named the blocking package twice — *"scipy requires scipy 1.11.4 requires
numpy…"*. It now reads once, with the version.
- Clearing the cache reported a total that left out one of the two tool environments.
PRs [#51](https://github.com/poli0981/pipdock/pull/51),
[#52](https://github.com/poli0981/pipdock/pull/52),
[#53](https://github.com/poli0981/pipdock/pull/53).
## 1.1.0 — 2026-08-14
Four smaller features, the day after 1.0.0.
### Added
- **Pin auto-suggest** — packages that many others depend on are offered for pinning, on the Pins
screen, with the count as the reason. The threshold is in Settings; zero turns it off.
- **Export and import** — write an environment as `requirements.txt` or `constraints.txt`, and read
a requirements file back in as an install queue. Lines PipDock will not act on (includes,
editable installs) are listed rather than silently dropped.
- **Disk usage** in Settings — what PipDock has written, and a way to clear the parts that are safe
to clear. `index.db` is shown but not clearable: it holds your settings, pins and consent record
as well as the package index.
- **`Ctrl+K`** — a command palette over every screen and action.
## 1.0.0 — 2026-08-14
First public release. Windows.
Bulk-manage packages across your Python environments, over pip or uv. Every change is previewed
before it runs, the environment is snapshotted before it is touched, and a batch reports back
package by package rather than stopping at the first failure.
- **Environments** discovered from the registry, `py -0p`, uv-managed installs and the usual venv
folder names, with a *Browse…* fallback still to come.
- **Installed / Updates** — the whole environment, what is outdated, and a preview that explains
what is holding a package back and which installed package declared the constraint. No engine
reports that; PipDock derives it.
- **Snapshots and rollback**, including a rollback of a rollback.
- **Pins**, so a bulk update leaves what you have chosen to keep.
- **An uninstall guard** that refuses a removal other packages depend on, naming them and their
constraints.
- **Code Health** — deptry, vulture and ruff over a project folder, from an isolated environment
PipDock builds for itself, with a gated `ruff --fix`.
- **English and Vietnamese** throughout the interface.
- **A command line** with the same behaviour, documented exit codes and `--json`.
No telemetry, no account, no self-update. It connects to pypi.org and nowhere else.
+50
View File
@@ -0,0 +1,50 @@
# Changelog
One file per **major line**. `1.x.md` holds every 1.y.z release; `0.x.md` would have held the
pre-1.0 ones had any been published (none were — the first release was 1.0.0, and `0.1.0` existed
only as a working version in the manifests).
| File | Covers |
|---|---|
| [`1.x.md`](1.x.md) | 1.0.0 → current |
A **pre-release line gets its own file**, named for the line it leads to — `2.0-beta.md` for
`2.0.0-beta.1` onward. It is not merged into `2.x.md` when the line goes stable: the beta file is
what someone reads to find out *when* a behaviour changed during the run-up, and folding it in
would double the length of the file people actually read while losing that.
## When a major line gets long, split by minor range
The point of this directory is that a reader opens one file and finds their version without
scrolling past releases they do not care about. So the rule is about **reading length**, not about
release count:
**Split when a file passes roughly 600 lines**, into contiguous minor ranges — `1.0-1.4.md`,
`1.5-1.9.md` — and leave `1.x.md` as a stub pointing at both, so an old link never 404s. Add the
new files to the table above in the same commit.
Two things that make the split cheap when it comes:
- **Never renumber an existing file.** A range file is named for the range it holds and keeps that
name forever, even after the next split. `1.0-1.4.md` does not become `1.0-1.6.md`.
- **Newest first within a file**, so the top of the file is the part most people want and the
split point is always at the bottom.
## What goes in an entry
One `## x.y.z — YYYY-MM-DD` heading per release, newest first, and under it only what a *user* of
PipDock would notice: added, changed, fixed, and anything they have to do (a consent gate that
re-shows, a cache that needs clearing). Internals belong in `docs/ROADMAP.md`, which records what a
slice cost and what it taught; the two are deliberately different documents for different readers,
the way `docs/CLI-GUIDE.md` and `docs/CLI-SPEC.md` are.
Link the release's PRs. Do not quote commit counts or defect tallies — a number written about the
repository inside the repository goes stale the moment it is committed, which
`docs/AI-DISCLOSURE.md` learned three times.
## One version per session
Each working session takes **one** item — a `docs/ROADMAP.md` entry, or something that surfaced
while doing it — takes it deep, tests it properly, and ships it as **one version**, plus a patch
release if that version needs a hotfix. That is why entries here are small and frequent rather than
large and rare, and it is written down in `CLAUDE.md` under *Conventions*.