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:
1 parent
99a25f3fa4
commit
39a0c54f05
4 files changed
+153
No files matched your search
@@ -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.
|
||||||
@@ -49,6 +49,15 @@ failed package never aborts a batch (skip-and-continue, then a `"13 successful,
|
|||||||
|
|
||||||
## Conventions
|
## 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`)
|
- Crates `pipdock-*`; React components prefixed `Pd` (`PdPackageRow`, `PdConflictDialog`)
|
||||||
- Tauri identifier `com.skullmute.pipdock`; CLI binary `pipdock`
|
- Tauri identifier `com.skullmute.pipdock`; CLI binary `pipdock`
|
||||||
- Frontend lives in `ui/`, but `package.json` sits at the **repo root** so the ops-repo
|
- Frontend lives in `ui/`, but `package.json` sits at the **repo root** so the ops-repo
|
||||||
|
|||||||
@@ -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.
|
||||||
@@ -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*.
|
||||||
Reference in new issue
Block a user