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
|
||||
|
||||
- **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
|
||||
|
||||
@@ -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