From b1b85165eef13d3ab98e0d5255e240ffb7fcda04 Mon Sep 17 00:00:00 2001 From: Yuma Takino <36617106+tappe9@users.noreply.github.com> Date: Wed, 2 Sep 2026 14:04:07 +0900 Subject: [PATCH 01/10] test(docs): require published 0.2.0 state --- scripts/test-public-documentation.py | 85 ++++++++++++++++++---------- 1 file changed, 56 insertions(+), 29 deletions(-) diff --git a/scripts/test-public-documentation.py b/scripts/test-public-documentation.py index be0a365..11d7e09 100644 --- a/scripts/test-public-documentation.py +++ b/scripts/test-public-documentation.py @@ -1,5 +1,5 @@ #!/usr/bin/env python3 -"""Verify that public documentation matches pgdumpx 0.2.0.""" +"""Verify that public documentation matches the published pgdumpx 0.2.0 release.""" from __future__ import annotations @@ -10,11 +10,11 @@ REQUIRED_SNIPPETS = { "README.md": [ - "Current source version: `0.2.0`", - "## Installation", - "### From crates.io", - "### From source", - "Registry commands require", + "`pgdumpx 0.2.0` is published on crates.io", + "https://crates.io/crates/pgdumpx", + "https://crates.io/crates/pgdumpx-cli", + "https://docs.rs/pgdumpx/0.2.0/pgdumpx/", + "cargo install pgdumpx-cli --version 0.2.0 --locked", "`Archive::open_path`", "`TableSelector`", "`ExtractionPlan`", @@ -22,11 +22,11 @@ "`find_first_equal_with_limits`", ], "README.ja.md": [ - "現在のソースバージョン: `0.2.0`", - "## インストール", - "### crates.io から", - "### ソースから", - "crates.ioでpackage versionを確認してから", + "`pgdumpx 0.2.0`はcrates.ioで公開済みです", + "https://crates.io/crates/pgdumpx", + "https://crates.io/crates/pgdumpx-cli", + "https://docs.rs/pgdumpx/0.2.0/pgdumpx/", + "cargo install pgdumpx-cli --version 0.2.0 --locked", "`Archive::open_path`", "`TableSelector`", "`ExtractionPlan`", @@ -34,12 +34,11 @@ "`find_first_equal_with_limits`", ], "ROADMAP.md": [ - "## v0.2 — Completed", - "### Delivered", - "#57–#63", - "#70–#78", - "#89", - "#92", + "Status: **v0.2.0 released", + "## v0.2 — Completed and released", + "https://crates.io/crates/pgdumpx/0.2.0", + "https://crates.io/crates/pgdumpx-cli/0.2.0", + "https://github.com/tappe9/pgdumpx/releases/tag/v0.2.0", "## v0.3+ — Deferred candidates", ], "docs/API-DESIGN.md": [ @@ -51,9 +50,9 @@ "## 16.1 Exact named-column equality", ], "SECURITY.md": [ - "latest published 0.2.x release", - "current `main`", - "If no package has been published yet", + "Security fixes target the latest published 0.2.x release and the current `main` branch.", + "https://crates.io/crates/pgdumpx", + "https://github.com/tappe9/pgdumpx/releases", ], "CONTRIBUTING.md": [ "python3 scripts/test-public-documentation.py", @@ -61,34 +60,62 @@ "python3 scripts/verify-release-packaging.py", "[Release procedure](docs/RELEASING.md)", ], + "docs/PACKAGING.md": [ + "Status: **0.2.0 published on crates.io**", + "`pgdumpx 0.2.0` — published 2026-09-01 12:36:29 UTC", + "`pgdumpx-cli 0.2.0` — published 2026-09-01 12:36:56 UTC", + "ef4d0cb73fdf21a87dd7e2515adf83cdf4415e13707dfed41bd9ad4576e9dd6b", + "9a6f0d8f690d4ab65bc9a2e5079397966b12d473629bdd21cfc939bcb56414fe", + ], + "docs/RELEASING.md": [ + "## 0.2.0 completion record", + "Published library package", + "Published CLI package", + "GitHub Release", + "https://github.com/tappe9/pgdumpx/releases/tag/v0.2.0", + ], + "docs/release-notes/0.2.0.md": [ + "## Published artifacts", + "https://crates.io/crates/pgdumpx/0.2.0", + "https://crates.io/crates/pgdumpx-cli/0.2.0", + "https://docs.rs/pgdumpx/0.2.0/pgdumpx/", + "cargo install pgdumpx-cli --version 0.2.0 --locked", + ], } FORBIDDEN_SNIPPETS = { "README.md": [ + "Registry commands require the exact package version to be available", + "Check the exact versions before installing", "v0.2 is planned", "no v0.2 production code has merged yet", - "**Planned next:** v0.2", ], "README.ja.md": [ - "v0.2は[Tracking Issue #56]", + "registry commandを使うには、対象package versionがcrates.ioに存在する必要があります", + "crates.ioでpackage versionを確認してから", "v0.2のproduction codeはまだ`main`へmergeされていません", - "**次に実装するv0.2:**", ], "ROADMAP.md": [ + "the 0.2.0 publication process is tracked separately from source delivery", + "this roadmap does not infer their live state", "## v0.2 candidate", - "No production implementation exists yet", - ], - "docs/API-DESIGN.md": [ - "The current repository is still in the design phase", ], "SECURITY.md": [ + "If no package has been published yet", + "when one exists", "pgdumpx has no published release version yet", - "## Current v0.1 scope boundary", + ], + "docs/PACKAGING.md": [ + "registry publication pending credentials", + ], + "docs/release-notes/0.2.0.md": [ + "After both crates.io packages are published:", ], } ALIGNED_README_IDENTIFIERS = [ "0.2.0", + "pgdumpx-cli", "Archive::open_path", "TableSelector", "ExtractionPlan", @@ -146,7 +173,7 @@ def main() -> int: print(f" - {error}", file=sys.stderr) return 1 - print("public documentation contract passed for pgdumpx 0.2.0") + print("public documentation contract passed for published pgdumpx 0.2.0") return 0 From f7f5f768fbf43564686d62e2e4a92a8cc9ac88c7 Mon Sep 17 00:00:00 2001 From: Yuma Takino <36617106+tappe9@users.noreply.github.com> Date: Wed, 2 Sep 2026 14:06:03 +0900 Subject: [PATCH 02/10] docs: publish installation and artifact links --- README.md | 50 +++++++++++++++++++++++++++++++++++++------------- 1 file changed, 37 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index ca2ead2..d0ead07 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,14 @@ # pgdumpx +[![crates.io](https://img.shields.io/crates/v/pgdumpx.svg)](https://crates.io/crates/pgdumpx) +[![docs.rs](https://docs.rs/pgdumpx/badge.svg)](https://docs.rs/pgdumpx/0.2.0/pgdumpx/) +[![CI](https://github.com/tappe9/pgdumpx/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/tappe9/pgdumpx/actions/workflows/ci.yml) +[![MSRV](https://img.shields.io/badge/MSRV-1.85.0-blue.svg)](https://www.rust-lang.org/) +[![License](https://img.shields.io/badge/license-MIT%20OR%20Apache--2.0-blue.svg)](LICENSE-MIT) + **A bounded, byte-oriented row scanner for PostgreSQL custom-format dumps.** -> Current source version: `0.2.0`. The v0.1 foundation and v0.2 functionality are implemented. Registry commands require the exact package version to be available on crates.io; the source installation path works independently of registry publication. +> `pgdumpx 0.2.0` is published on crates.io as both a reusable Rust library and an installable CLI package. pgdumpx is a read-only Rust library and CLI for inspecting PostgreSQL custom-format (`pg_dump -Fc`) archives without restoring them into a database. @@ -14,8 +20,18 @@ A representative use case is: [日本語 README](README.ja.md) +## Published artifacts + +| Artifact | Version | Purpose | +| --- | --- | --- | +| [`pgdumpx`](https://crates.io/crates/pgdumpx/0.2.0) | `0.2.0` | Reusable Rust library | +| [`pgdumpx-cli`](https://crates.io/crates/pgdumpx-cli/0.2.0) | `0.2.0` | Installs the `pgdumpx` executable | +| [API documentation](https://docs.rs/pgdumpx/0.2.0/pgdumpx/) | `0.2.0` | Published library rustdoc | +| [GitHub Release](https://github.com/tappe9/pgdumpx/releases/tag/v0.2.0) | `v0.2.0` | Source release and release notes | + ## Current development status +- **v0.2.0 published:** the library, CLI package, annotated source tag, GitHub Release, and API documentation are available from the links above. - **v0.1 foundation completed:** metadata inspection, four compression backends, bounded raw extraction, COPY row parsing, first-match search, limits, fuzz/benchmark/CI evidence, rustdoc, and packaging verification. - **v0.2 completed:** file-oriented opening, owned byte-oriented selectors, reusable extraction plans, deterministic sequential multi-table extraction, metadata filtering, and exact named-column equality helpers are implemented. - **Correctness and maintenance follow-ups completed:** destination flush failures, aggregate metadata budgets, terminal row-reader errors, field-count validation, linear duplicate detection, finite CLI scan defaults, feature-matrix testing, scheduled fuzzing, advisory policy, and workflow hardening are included in the current source. @@ -112,26 +128,33 @@ All row searches remain sequential scans. The helpers add reusable selection pol ## Installation -### From crates.io - -Registry commands require `0.2.0` to be available on crates.io. Check the exact versions before installing or adding the dependency: +### CLI from crates.io ```bash -cargo info pgdumpx@0.2.0 -cargo info pgdumpx-cli@0.2.0 cargo install pgdumpx-cli --version 0.2.0 --locked +pgdumpx --version +pgdumpx --help ``` -Library consumers can add: +The package name is `pgdumpx-cli`; the installed executable is named `pgdumpx`. + +### Library from crates.io ```toml [dependencies] pgdumpx = "0.2.0" ``` +Published API documentation is available on [docs.rs](https://docs.rs/pgdumpx/0.2.0/pgdumpx/). Registry metadata can also be inspected with: + +```bash +cargo info pgdumpx@0.2.0 +cargo info pgdumpx-cli@0.2.0 +``` + ### From source -This path works independently of crates.io publication: +Use the source path to test the current `main` branch or local changes: ```bash git clone https://github.com/tappe9/pgdumpx.git @@ -188,7 +211,7 @@ The API keeps three resource concepts separate: `Limits::default()` is finite and compatibility-oriented, and `Archive::open_with_limits` accepts stricter caller-selected TOC/string/dependency/row/field bounds. `ScanLimits::default()` and `ScanLimits::unlimited()` leave both operation-level budgets unset. `max_rows = N` permits at most `N` complete rows to be yielded or evaluated, including a matching row. The decompressed-byte scan budget counts physical COPY bytes consumed by the parser—including field separators, row terminators, escape spellings, and the COPY terminator when consumed—not logical decoded field length or unread decoder/`BufRead` lookahead. A crossing row is not yielded or passed to the predicate, and exhaustion is returned as a typed resource error with limit and consumed-work context. -See [Public API design](docs/API-DESIGN.md) and the crate rustdoc for the complete public contract. +See [Public API design](docs/API-DESIGN.md) and the [published crate documentation](https://docs.rs/pgdumpx/0.2.0/pgdumpx/) for the complete public contract. ## CLI @@ -204,7 +227,7 @@ pgdumpx find --max-rows 100000 --max-decompressed-bytes 67108864 \ backup.dump public.orders order_number 123456 ``` -For table-oriented commands, `` contains exactly one ASCII `.` separator and non-empty schema and table components. SQL identifier quoting/escaping and identifiers containing `.` are not supported by the v0.1 CLI. Query identifiers/values at the CLI boundary are UTF-8; the Rust API remains byte-oriented. +For table-oriented commands, `` contains exactly one ASCII `.` separator and non-empty schema and table components. SQL identifier quoting/escaping and identifiers containing `.` are not supported by the current CLI grammar. Query identifiers/values at the CLI boundary are UTF-8; the Rust API remains byte-oriented. ### `inspect` / `list` @@ -306,7 +329,7 @@ These projects cover adjacent PostgreSQL dump use cases. pgdumpx keeps a deliber Each document has one primary responsibility to reduce duplication and drift: -- [README](README.md) / [日本語 README](README.ja.md) — product value, current implementation/release status, examples, and high-level scope; +- [README](README.md) / [日本語 README](README.ja.md) — product value, published release status, examples, and high-level scope; - [Requirements](docs/REQUIREMENTS.md) — normative v0.1 behavior and Definition of Done; - [Architecture](ARCHITECTURE.md) — implemented boundaries and data flow; - [Public API design](docs/API-DESIGN.md) — implemented Rust API semantics and ownership/resource contracts; @@ -315,9 +338,10 @@ Each document has one primary responsibility to reduce duplication and drift: - [Compatibility matrix](docs/COMPATIBILITY.md) — target versus fixture-verified support; - [Bounded raw extraction](docs/RAW-EXTRACTION.md) — raw byte-budget and partial-output semantics; - [`find` scan-budget policy](docs/FIND-SCAN-LIMITS.md) — finite CLI defaults, evidence, boundary semantics, and migration guidance; -- [Packaging audit](docs/PACKAGING.md) — package/license/runtime dependency boundary; +- [Packaging audit](docs/PACKAGING.md) — package/license/runtime dependency boundary and published package record; +- [Release process](docs/RELEASING.md) — release procedure and completed release record; - [v0.1 release audit](docs/V0.1-RELEASE-AUDIT.md) — final DoD-to-evidence mapping; -- [Roadmap](ROADMAP.md) — delivered v0.1/v0.2 work and deferred candidate scope; +- [Roadmap](ROADMAP.md) — delivered and published v0.1/v0.2 work plus deferred candidate scope; - [Architecture Decision Records](docs/adr/) — accepted and superseded design decisions; - [Contributing](CONTRIBUTING.md) — contribution and document-update policy; - [Security policy](SECURITY.md) — vulnerability reporting and resource-threat model. From 34f4965b24b580f4d4665bb21aa72d4ac70adc0e Mon Sep 17 00:00:00 2001 From: Yuma Takino <36617106+tappe9@users.noreply.github.com> Date: Wed, 2 Sep 2026 14:07:15 +0900 Subject: [PATCH 03/10] docs: align Japanese release documentation --- README.ja.md | 50 +++++++++++++++++++++++++++++++++++++------------- 1 file changed, 37 insertions(+), 13 deletions(-) diff --git a/README.ja.md b/README.ja.md index 924534d..73c0965 100644 --- a/README.ja.md +++ b/README.ja.md @@ -1,8 +1,14 @@ # pgdumpx +[![crates.io](https://img.shields.io/crates/v/pgdumpx.svg)](https://crates.io/crates/pgdumpx) +[![docs.rs](https://docs.rs/pgdumpx/badge.svg)](https://docs.rs/pgdumpx/0.2.0/pgdumpx/) +[![CI](https://github.com/tappe9/pgdumpx/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/tappe9/pgdumpx/actions/workflows/ci.yml) +[![MSRV](https://img.shields.io/badge/MSRV-1.85.0-blue.svg)](https://www.rust-lang.org/) +[![License](https://img.shields.io/badge/license-MIT%20OR%20Apache--2.0-blue.svg)](LICENSE-MIT) + **PostgreSQL Custom Formatをrestoreせず、byte-orientedなrowとして安全にscanするRustライブラリ / CLI。** -> 現在のソースバージョン: `0.2.0`。v0.1のfoundationとv0.2の機能は実装済みです。registry commandを使うには、対象package versionがcrates.ioに存在する必要があります。ソースからのinstallはregistry公開状態に依存しません。 +> `pgdumpx 0.2.0`はcrates.ioで公開済みです。再利用可能なRustライブラリと、install可能なCLI packageの両方を提供します。 pgdumpxは、PostgreSQL Custom Format (`pg_dump -Fc`) archiveを、データベースへrestoreせずに検査するread-onlyのRustライブラリ / CLIです。 @@ -14,8 +20,18 @@ pgdumpxは、PostgreSQL Custom Format (`pg_dump -Fc`) archiveを、データベ [English README](README.md) +## 公開成果物 + +| 成果物 | Version | 用途 | +| --- | --- | --- | +| [`pgdumpx`](https://crates.io/crates/pgdumpx/0.2.0) | `0.2.0` | 再利用可能なRustライブラリ | +| [`pgdumpx-cli`](https://crates.io/crates/pgdumpx-cli/0.2.0) | `0.2.0` | `pgdumpx` executableをinstallするCLI package | +| [API documentation](https://docs.rs/pgdumpx/0.2.0/pgdumpx/) | `0.2.0` | 公開済みlibrary rustdoc | +| [GitHub Release](https://github.com/tappe9/pgdumpx/releases/tag/v0.2.0) | `v0.2.0` | source releaseとrelease notes | + ## 現在の開発状況 +- **v0.2.0公開完了:** library、CLI package、annotated source tag、GitHub Release、API documentationを上記リンクから利用できます。 - **v0.1 foundation完了:** metadata inspection、4種類のcompression backend、bounded raw extraction、COPY row parsing、first-match search、各種limits、fuzz / benchmark / CI evidence、rustdoc、packaging verification。 - **v0.2完了:** file-oriented opening、owned byte-oriented selector、reusable extraction plan、deterministicなsequential multi-table extraction、metadata filtering、exact named-column equality helperを実装済みです。 - **correctness / maintenance follow-up完了:** destination flush failure、aggregate metadata budget、terminal row-reader error、field-count validation、linear duplicate detection、finite CLI scan default、feature matrix test、scheduled fuzz、advisory policy、workflow hardeningを現在のsourceに含みます。 @@ -112,26 +128,33 @@ unsupported representationはCOPY textとして推測せず、row APIからtyped ## インストール -### crates.io から - -crates.ioでpackage versionを確認してからinstallまたはdependency追加を行ってください。次のregistry commandには`0.2.0`がcrates.ioに存在することが必要です。 +### crates.ioからCLIをinstall ```bash -cargo info pgdumpx@0.2.0 -cargo info pgdumpx-cli@0.2.0 cargo install pgdumpx-cli --version 0.2.0 --locked +pgdumpx --version +pgdumpx --help ``` -library consumerは次を追加できます。 +package名は`pgdumpx-cli`、installされるexecutable名は`pgdumpx`です。 + +### crates.ioからlibraryを利用 ```toml [dependencies] pgdumpx = "0.2.0" ``` +公開済みAPI documentationは[docs.rs](https://docs.rs/pgdumpx/0.2.0/pgdumpx/)で確認できます。registry metadataは次のcommandでも確認できます。 + +```bash +cargo info pgdumpx@0.2.0 +cargo info pgdumpx-cli@0.2.0 +``` + ### ソースから -この手順はcrates.ioの公開状態に依存しません。 +現在の`main`やlocal変更を試す場合はsource pathを利用します。 ```bash git clone https://github.com/tappe9/pgdumpx.git @@ -188,7 +211,7 @@ APIでは次を別のlimitとして扱います。 `Limits::default()`はfiniteなcompatibility-oriented defaultで、`Archive::open_with_limits`ではTOC / string / dependency / row / fieldへより厳しいlimitを指定できます。`ScanLimits::default()`と`ScanLimits::unlimited()`はoperation-levelの2つのoptional budgetを未設定にします。`max_rows = N`では、一致rowを含めて最大`N`件のcomplete rowだけをyield / evaluateできます。decompressed-byte budgetは、field separator、row terminator、escape spelling、消費したCOPY terminatorを含む、parserが消費した物理COPY byteを数えます。logical fieldのdecode後lengthや、decoder / `BufRead`が先読みした未消費byteは数えません。budgetをcrossするrowはyieldもpredicate評価もされず、limit / consumed-work contextを持つtyped resource errorを返します。 -詳細は[Public API design](docs/API-DESIGN.md)とcrate rustdocを参照してください。 +詳細は[Public API design](docs/API-DESIGN.md)と[公開済みcrate documentation](https://docs.rs/pgdumpx/0.2.0/pgdumpx/)を参照してください。 ## CLI @@ -204,7 +227,7 @@ pgdumpx find --max-rows 100000 --max-decompressed-bytes 67108864 \ backup.dump public.orders order_number 123456 ``` -table-oriented commandの``はASCIIの`.`をちょうど1個含み、schema / tableの両componentをnon-emptyとします。SQL identifierのquote / escapeや`.`を含むidentifierはv0.1 CLIでは未対応です。CLI境界のquery identifier / valueはUTF-8で、Rust APIはbyte-orientedのままです。 +table-oriented commandの``はASCIIの`.`をちょうど1個含み、schema / tableの両componentをnon-emptyとします。SQL identifierのquote / escapeや`.`を含むidentifierは現在のCLI grammarでは未対応です。CLI境界のquery identifier / valueはUTF-8で、Rust APIはbyte-orientedのままです。 ### `inspect` / `list` @@ -306,7 +329,7 @@ v0.1の最終Definition of Done evidence mappingは[docs/V0.1-RELEASE-AUDIT.md]( 各documentのprimary responsibilityを分け、重複とdriftを抑えます。 -- [README](README.md) / [日本語 README](README.ja.md) — product value、現在の実装/release status、example、high-level scope +- [README](README.md) / [日本語 README](README.ja.md) — product value、公開済みrelease status、example、high-level scope - [Requirements](docs/REQUIREMENTS.md) — normative v0.1 behaviorとDefinition of Done - [Architecture](ARCHITECTURE.md) — 実装済みboundaryとdata flow - [Public API design](docs/API-DESIGN.md) — 実装済みRust API semanticsとownership/resource contract @@ -315,9 +338,10 @@ v0.1の最終Definition of Done evidence mappingは[docs/V0.1-RELEASE-AUDIT.md]( - [Compatibility matrix](docs/COMPATIBILITY.md) — targetとfixture-verified supportの区別 - [Bounded raw extraction](docs/RAW-EXTRACTION.md) — raw byte-budget / partial-output semantics - [`find` scan-budget policy](docs/FIND-SCAN-LIMITS.md) — finite CLI default、根拠、boundary、migration guidance -- [Packaging audit](docs/PACKAGING.md) — package/license/runtime dependency boundary +- [Packaging audit](docs/PACKAGING.md) — package/license/runtime dependency boundaryと公開済みpackage record +- [Release process](docs/RELEASING.md) — release procedureと完了済みrelease record - [v0.1 release audit](docs/V0.1-RELEASE-AUDIT.md) — 最終DoD-to-evidence mapping -- [Roadmap](ROADMAP.md) — delivered v0.1 / v0.2 work、deferred candidate scope +- [Roadmap](ROADMAP.md) — delivered / published v0.1・v0.2 work、deferred candidate scope - [Architecture Decision Records](docs/adr/) — accepted / superseded design decisions - [Contributing](CONTRIBUTING.md) — contribution / document-update policy - [Security policy](SECURITY.md) — vulnerability reporting / resource-threat model From 946b25b3e64d6a0d7de7928476dbbfbfd3207cc9 Mon Sep 17 00:00:00 2001 From: Yuma Takino <36617106+tappe9@users.noreply.github.com> Date: Wed, 2 Sep 2026 14:07:49 +0900 Subject: [PATCH 04/10] docs: record published package state --- docs/PACKAGING.md | 29 +++++++++++++++++++++++++---- 1 file changed, 25 insertions(+), 4 deletions(-) diff --git a/docs/PACKAGING.md b/docs/PACKAGING.md index af2e995..3ee4f51 100644 --- a/docs/PACKAGING.md +++ b/docs/PACKAGING.md @@ -1,8 +1,29 @@ # Packaging and dependency constraints -Status: **0.2.0 publication preflight; registry publication pending credentials** +Status: **0.2.0 published on crates.io** -This document records the package, dependency, and staged-verification boundary for the first public release. +This document records the package, dependency, staged-verification, and publication boundary for the first public release. + +## Published 0.2.0 record + +The two workspace packages were published in dependency order and remain non-yanked: + +- `pgdumpx 0.2.0` — published 2026-09-01 12:36:29 UTC; +- `pgdumpx-cli 0.2.0` — published 2026-09-01 12:36:56 UTC. + +The crates.io package checksums recorded by the registry index are: + +```text +pgdumpx 0.2.0 ef4d0cb73fdf21a87dd7e2515adf83cdf4415e13707dfed41bd9ad4576e9dd6b +pgdumpx-cli 0.2.0 9a6f0d8f690d4ab65bc9a2e5079397966b12d473629bdd21cfc939bcb56414fe +``` + +Published package pages: + +- +- + +The matching source release is [`v0.2.0`](https://github.com/tappe9/pgdumpx/releases/tag/v0.2.0), created from commit `aaae67749e3f389bdde5c28f555436508e219fc8` after both packages were visible in the registry. Published crate archives and versions are immutable; later corrections require a new version unless yanking is justified by a severe correctness or security defect. ## Package set and versioning @@ -66,10 +87,10 @@ The audit performs all of the following without uploading a package: 8. runs `cargo publish --dry-run -p pgdumpx --locked`; 9. verifies that the source tree remains unchanged. -The CLI package is assembled and build-verified through workspace packaging before the library exists in crates.io. Its final publication dry-run is intentionally staged after `pgdumpx 0.2.0` is visible in the registry: +The CLI package is assembled and build-verified through workspace packaging before a new library version exists in crates.io. Its final publication dry-run is intentionally staged after the matching `pgdumpx` version is visible in the registry: ```bash cargo publish --dry-run -p pgdumpx-cli --locked ``` -See `RELEASING.md` for the complete publication order, registry verification, tag creation, and recovery procedure. The preflight never uploads packages, creates tags, or creates a GitHub Release. +See [RELEASING.md](RELEASING.md) for the complete publication order, registry verification, tag creation, and recovery procedure. The preflight never uploads packages, creates tags, or creates a GitHub Release. From 62f4ebd39ec2acd35a282d5cd595f10d89f72432 Mon Sep 17 00:00:00 2001 From: Yuma Takino <36617106+tappe9@users.noreply.github.com> Date: Wed, 2 Sep 2026 14:08:13 +0900 Subject: [PATCH 05/10] docs: record completed release procedure --- docs/RELEASING.md | 29 +++++++++++++++++++++++------ 1 file changed, 23 insertions(+), 6 deletions(-) diff --git a/docs/RELEASING.md b/docs/RELEASING.md index ea5d5df..05d02a9 100644 --- a/docs/RELEASING.md +++ b/docs/RELEASING.md @@ -1,6 +1,21 @@ # Release process -This document defines the staged publication procedure for `pgdumpx 0.2.0`, the first public release of both workspace packages. +This document defines the staged publication procedure for `pgdumpx` and records the completed `0.2.0` first public release. + +## 0.2.0 completion record + +The release sequence completed successfully on 2026-09-01 UTC: + +| Item | Result | +| --- | --- | +| Published library package | [`pgdumpx 0.2.0`](https://crates.io/crates/pgdumpx/0.2.0), published 2026-09-01 12:36:29 UTC | +| Published CLI package | [`pgdumpx-cli 0.2.0`](https://crates.io/crates/pgdumpx-cli/0.2.0), published 2026-09-01 12:36:56 UTC | +| Release commit | `aaae67749e3f389bdde5c28f555436508e219fc8` | +| Git tag | `v0.2.0`, resolving to the release commit | +| GitHub Release | | +| Library documentation | | + +Both crates.io versions remain non-yanked. Published versions are immutable; this completion record does not authorize rebuilding or overwriting the released archives. ## Release identity @@ -16,6 +31,8 @@ This document defines the staged publication procedure for `pgdumpx 0.2.0`, the Both packages use the same version for the initial release train. The CLI retains a path dependency for workspace development and a matching `0.2.0` version requirement for published packages. +For a future release, replace the version, tag, release-notes path, and changelog range consistently before executing these steps. + ## Preconditions Use a clean checkout of the exact release commit on `main`. Confirm that there are no release-blocking Issues or pull requests and that CI, dependency advisories, scheduled-fuzz policy, and Release Packaging are green for that commit. @@ -99,17 +116,17 @@ cargo info pgdumpx@0.2.0 cargo info pgdumpx-cli@0.2.0 ``` -The tag must resolve to `RELEASE_SHA`. docs.rs builds are asynchronous; verify the `pgdumpx 0.2.0` documentation after the registry has accepted the package. The CLI package intentionally has no public Rust library target, so its primary usage documentation remains the repository README and CLI help. +The tag must resolve to `RELEASE_SHA`. Verify the `pgdumpx` library documentation on docs.rs after the registry accepts the package. The CLI package intentionally has no public Rust library target, so its primary usage documentation remains the repository README and CLI help. ## Partial publication recovery ### Library published, CLI not published -If the library publishes but the CLI fails, do not create `v0.2.0` or a GitHub Release and do not attempt to overwrite `pgdumpx 0.2.0`. +If the library publishes but the CLI fails, do not create the corresponding tag or GitHub Release and do not attempt to overwrite the published library version. -- If the CLI package itself is the only problem and `pgdumpx-cli 0.2.0` was never accepted, correct the CLI or release metadata, re-run every gate, and publish the same still-unpublished CLI version against `pgdumpx 0.2.0`. -- If the correction requires changing the published library API or package, prepare `0.2.1` for both packages and repeat the library-first sequence. -- Yank `pgdumpx 0.2.0` only for a severe correctness or security defect that justifies excluding it from new dependency resolution. Yanking does not delete the published archive. +- If the CLI package itself is the only problem and its version was never accepted, correct the CLI or release metadata, re-run every gate, and publish the same still-unpublished CLI version against the published library. +- If the correction requires changing the published library API or package, prepare the next patch version for both packages and repeat the library-first sequence. +- Yank a published library only for a severe correctness or security defect that justifies excluding it from new dependency resolution. Yanking does not delete the published archive. ### Packages published, tag or Release creation failed From 3a7f0f1ee26cc780eb09e6458e17737a75855ff6 Mon Sep 17 00:00:00 2001 From: Yuma Takino <36617106+tappe9@users.noreply.github.com> Date: Wed, 2 Sep 2026 14:08:43 +0900 Subject: [PATCH 06/10] docs: define supported published security versions --- SECURITY.md | 47 +++++++++-------------------------------------- 1 file changed, 9 insertions(+), 38 deletions(-) diff --git a/SECURITY.md b/SECURITY.md index a759e44..a67d433 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -4,9 +4,15 @@ pgdumpx parses archive files that may be attacker controlled. Parser safety and ## Supported versions -Security fixes target the latest published 0.2.x release, when one exists, and the current `main` branch. A published release is the stable package source for users; `main` may contain unreleased changes and should be identified by exact commit when reporting or testing an issue. +Security fixes target the latest published 0.2.x release and the current `main` branch. -If no package has been published yet, use the current source tree and report the exact commit. Source preparation, a Cargo version, or a changelog entry does not by itself prove that a version is available from crates.io. Check the registry and repository release state independently. +| Channel | Support status | Location | +| --- | --- | --- | +| Latest stable release | Supported | [`pgdumpx 0.2.0`](https://crates.io/crates/pgdumpx/0.2.0) and [`v0.2.0`](https://github.com/tappe9/pgdumpx/releases/tag/v0.2.0) | +| Current `main` | Supported for unreleased fixes | Identify reports and test results by exact commit | +| Older or yanked releases | Case-by-case | Upgrade to the latest supported patch release where possible | + +Registry history is available at , and source releases are available at . A published release is the stable package source for users; `main` may contain unreleased changes and should be identified by exact commit when reporting or testing an issue. ## Reporting a vulnerability @@ -92,43 +98,8 @@ Raw extraction byte limits count decompressed bytes exposed to the caller or cop ## COPY representation boundary -The v0.1 row API parses supported pg_dump-generated COPY text table data only. INSERT-based dump modes and Binary COPY are not treated as valid COPY text merely because their containing Custom Format entry is readable. +The row API parses supported pg_dump-generated COPY text table data only. INSERT-based dump modes and Binary COPY are not treated as valid COPY text merely because their containing Custom Format entry is readable. Unsupported representations fail explicitly before row parsing where the necessary metadata is available. See [COPY text contract](docs/COPY-TEXT.md) for the byte-level row contract. - -## Dependency advisory policy - -The committed `Cargo.lock` is checked with cargo-deny `0.20.2` and the repository-root `[advisories]` policy. Dependency-related pull requests and `main` pushes run the check, a daily `03:17 UTC` schedule refreshes the RustSec database without requiring a source change, and maintainers can use `workflow_dispatch` for manual validation. - -When a check fails: - -1. read the cargo-deny diagnostic for the advisory ID, affected crate/version, and dependency path; -2. identify whether the affected dependency is used by the library, CLI, development, benchmark, or fuzz scope; -3. prefer updating the lockfile, upgrading or replacing the dependency, or reducing the affected feature surface; -4. rerun the repository quality gates and `cargo deny --locked check advisories`; -5. do not place exploit details, sensitive crash inputs, credentials, or private archive data in public logs or issues. - -An exception is a temporary last resort. `deny.toml` must use an object ignore with an advisory ID or yanked crate plus a non-empty reason. `advisory-exceptions.toml` must contain one matching record with the same reason, affected scope, removal condition, and either a review date or tracking Issue. `scripts/verify-advisory-policy.py` rejects bare IDs, incomplete or unmatched metadata, and metadata left behind after an ignore is removed. Delete both records when the removal condition is met. - -For cargo-deny tool or schema updates, review the current official release and configuration documentation, update the exact version in the workflow, tests, and documentation together, install it with `--locked`, and manually dispatch the workflow before merging. License, source allowlist, and duplicate-version checks remain outside this policy. - -## Fuzzing - -The baseline invariants are: - -```text -arbitrary archive bytes -> successful parse/extraction or typed error, never parser panic -arbitrary COPY bytes -> rows or typed error, never parser panic -``` - -The committed `cargo-fuzz` harnesses cover raw archive opening, TOC/metadata parsing with structural limits, selected-entry block/chunk framing, COPY row/escape parsing, COPY column metadata, and structural/scan/raw-output limit accounting. Each harness uses bounded inputs and the normal production parser/limit paths. - -Pull-request CI compiles all six targets and retains the short deterministic 64-run smoke gate. A dedicated workflow runs all six targets weekly and on manual dispatch with a finite five-minute budget per target, 64 KiB maximum inputs, a 10-second individual-input timeout, and a 15-minute job timeout. Relevant branch pushes use a 10-second target budget to validate the workflow without turning pull-request CI into a long campaign. - -The campaign runner saves each command's exit status and execution log, allows the `if: always()` artifact step to collect target failure artifacts and logs, then re-emits the original status. Crash, hang, sanitizer, and other non-zero results therefore remain job failures. Artifacts are target/commit/run-specific, retained for 7 days, and exclude corpus evolution. - -The repository campaign may use only committed, reviewed, non-sensitive seeds and generated mutations. Actions artifacts are not a confidential vulnerability-disclosure channel: never introduce production dumps, customer data, credentials, personal data, proprietary inputs, or embargoed vulnerability material into the scheduled workflow. Security-sensitive findings must move to private reporting before payloads or exploit details are shared. - -When fuzzing finds a panic, hang, sanitizer finding, or boundary defect, minimize the input and add a deterministic failing regression test through the same production path before changing production code. A discovered corpus input may be committed only after provenance, checksum, minimization, public-distribution safety, and reviewer approval are recorded. Reproducible commands, target frequency, bounds, artifact handling, triage, and corpus policy are documented in [`fuzz/README.md`](fuzz/README.md). From f964e874e5863e957f0cb8a07e5728fb5fc076b1 Mon Sep 17 00:00:00 2001 From: Yuma Takino <36617106+tappe9@users.noreply.github.com> Date: Wed, 2 Sep 2026 14:08:55 +0900 Subject: [PATCH 07/10] docs: link published release artifacts --- docs/release-notes/0.2.0.md | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/docs/release-notes/0.2.0.md b/docs/release-notes/0.2.0.md index d30f505..702a494 100644 --- a/docs/release-notes/0.2.0.md +++ b/docs/release-notes/0.2.0.md @@ -2,6 +2,15 @@ `pgdumpx 0.2.0` is the first public release of the read-only Rust library and CLI for bounded inspection, extraction, and row scanning of PostgreSQL custom-format dumps. +## Published artifacts + +- Library package: +- CLI package: +- Library API documentation: +- Source release: + +Both crates.io packages were published on 2026-09-01 UTC and remain non-yanked. The source release points to commit `aaae67749e3f389bdde5c28f555436508e219fc8`. + ## Highlights - Inspect archive metadata and table entries without restoring into a PostgreSQL server. @@ -24,10 +33,11 @@ The release includes separate structural, raw-output, row, and decompressed-byte ## Installation -After both crates.io packages are published: +Install the published CLI package: ```bash cargo install pgdumpx-cli --version 0.2.0 --locked +pgdumpx --version pgdumpx --help ``` From ff85a7c804c524f9a0eb824b1bb7ab201ec603ed Mon Sep 17 00:00:00 2001 From: Yuma Takino <36617106+tappe9@users.noreply.github.com> Date: Wed, 2 Sep 2026 14:09:53 +0900 Subject: [PATCH 08/10] docs: mark v0.2.0 released --- ROADMAP.md | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) diff --git a/ROADMAP.md b/ROADMAP.md index 9c630c8..b0256c7 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -1,8 +1,8 @@ # pgdumpx Roadmap -Status: **v0.1 foundation complete; v0.2 implementation complete; the 0.2.0 publication process is tracked separately from source delivery.** +Status: **v0.2.0 released; v0.1 foundation and v0.2 implementation complete; v0.3+ candidates remain deferred.** -This roadmap records completed v0.1/v0.2 work and explicitly deferred candidates. The normative v0.1 contract remains in `docs/REQUIREMENTS.md`, final v0.1 evidence is mapped in `docs/V0.1-RELEASE-AUDIT.md`, GitHub Tracking Issue #30 records the v0.1 sequence, and [Tracking Issue #56](https://github.com/tappe9/pgdumpx/issues/56) records the completed v0.2 sequence. +This roadmap records completed v0.1/v0.2 work, the published `0.2.0` release, and explicitly deferred candidates. The normative v0.1 contract remains in `docs/REQUIREMENTS.md`, final v0.1 evidence is mapped in `docs/V0.1-RELEASE-AUDIT.md`, GitHub Tracking Issue #30 records the v0.1 sequence, and [Tracking Issue #56](https://github.com/tappe9/pgdumpx/issues/56) records the completed v0.2 sequence. ## v0.1 — Bounded row scanning for Custom Format archives @@ -179,7 +179,7 @@ Stable exit behavior: No-match remains distinct from failure. -## v0.2 — Completed +## v0.2 — Completed and released The v0.2 implementation builds on the v0.1 `Read + Seek`, validated-entry, decompression, row-parser, and raw-output paths. It preserves the single mutable seekable-source invariant and does not add parallel or indexed alternatives. @@ -190,7 +190,15 @@ The v0.2 implementation builds on the v0.1 `Read + Seek`, validated-entry, decom - [#89](https://github.com/tappe9/pgdumpx/issues/89) hardened GitHub Actions with pinned dependencies, bounded execution, least-privilege permissions, and cancellation policy. - [#92](https://github.com/tappe9/pgdumpx/issues/92) prepared reproducible `pgdumpx 0.2.0` and `pgdumpx-cli 0.2.0` package metadata, changelog, release notes, packaging verification, and staged release instructions. -The `0.2.0` source and package contract is complete. Registry publication, the annotated tag, and the GitHub Release follow the independently verified process in `docs/RELEASING.md`; this roadmap does not infer their live state. +### Published artifacts + +- Library: +- CLI: +- Library API documentation: +- GitHub Release: +- Release commit: `aaae67749e3f389bdde5c28f555436508e219fc8` + +The library and CLI packages were published on 2026-09-01 UTC in dependency order and remain non-yanked. The annotated `v0.2.0` tag and GitHub Release point to the verified release commit. See `docs/RELEASING.md` for the completed release record and reusable staged procedure. ## v0.3+ — Deferred candidates From 53ae6ce128b3b8e8670c1e7cdfaf271ddc3974ce Mon Sep 17 00:00:00 2001 From: Yuma Takino <36617106+tappe9@users.noreply.github.com> Date: Wed, 2 Sep 2026 14:12:02 +0900 Subject: [PATCH 09/10] docs: preserve security maintenance guidance --- SECURITY.md | 35 +++++++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) diff --git a/SECURITY.md b/SECURITY.md index a67d433..f528537 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -103,3 +103,38 @@ The row API parses supported pg_dump-generated COPY text table data only. INSERT Unsupported representations fail explicitly before row parsing where the necessary metadata is available. See [COPY text contract](docs/COPY-TEXT.md) for the byte-level row contract. + +## Dependency advisory policy + +The committed `Cargo.lock` is checked with cargo-deny `0.20.2` and the repository-root `[advisories]` policy. Dependency-related pull requests and `main` pushes run the check, a daily `03:17 UTC` schedule refreshes the RustSec database without requiring a source change, and maintainers can use `workflow_dispatch` for manual validation. + +When a check fails: + +1. read the cargo-deny diagnostic for the advisory ID, affected crate/version, and dependency path; +2. identify whether the affected dependency is used by the library, CLI, development, benchmark, or fuzz scope; +3. prefer updating the lockfile, upgrading or replacing the dependency, or reducing the affected feature surface; +4. rerun the repository quality gates and `cargo deny --locked check advisories`; +5. do not place exploit details, sensitive crash inputs, credentials, or private archive data in public logs or issues. + +An exception is a temporary last resort. `deny.toml` must use an object ignore with an advisory ID or yanked crate plus a non-empty reason. `advisory-exceptions.toml` must contain one matching record with the same reason, affected scope, removal condition, and either a review date or tracking Issue. `scripts/verify-advisory-policy.py` rejects bare IDs, incomplete or unmatched metadata, and metadata left behind after an ignore is removed. Delete both records when the removal condition is met. + +For cargo-deny tool or schema updates, review the current official release and configuration documentation, update the exact version in the workflow, tests, and documentation together, install it with `--locked`, and manually dispatch the workflow before merging. License, source allowlist, and duplicate-version checks remain outside this policy. + +## Fuzzing + +The baseline invariants are: + +```text +arbitrary archive bytes -> successful parse/extraction or typed error, never parser panic +arbitrary COPY bytes -> rows or typed error, never parser panic +``` + +The committed `cargo-fuzz` harnesses cover raw archive opening, TOC/metadata parsing with structural limits, selected-entry block/chunk framing, COPY row/escape parsing, COPY column metadata, and structural/scan/raw-output limit accounting. Each harness uses bounded inputs and the normal production parser/limit paths. + +Pull-request CI compiles all six targets and retains the short deterministic 64-run smoke gate. A dedicated workflow runs all six targets weekly and on manual dispatch with a finite five-minute budget per target, 64 KiB maximum inputs, a 10-second individual-input timeout, and a 15-minute job timeout. Relevant branch pushes use a 10-second target budget to validate the workflow without turning pull-request CI into a long campaign. + +The campaign runner saves each command's exit status and execution log, allows the `if: always()` artifact step to collect target failure artifacts and logs, then re-emits the original status. Crash, hang, sanitizer, and other non-zero results therefore remain job failures. Artifacts are target/commit/run-specific, retained for 7 days, and exclude corpus evolution. + +The repository campaign may use only committed, reviewed, non-sensitive seeds and generated mutations. Actions artifacts are not a confidential vulnerability-disclosure channel: never introduce production dumps, customer data, credentials, personal data, proprietary inputs, or embargoed vulnerability material into the scheduled workflow. Security-sensitive findings must move to private reporting before payloads or exploit details are shared. + +When fuzzing finds a panic, hang, sanitizer finding, or boundary defect, minimize the input and add a deterministic failing regression test through the same production path before changing production code. A discovered corpus input may be committed only after provenance, checksum, minimization, public-distribution safety, and reviewer approval are recorded. Reproducible commands, target frequency, bounds, artifact handling, triage, and corpus policy are documented in [`fuzz/README.md`](fuzz/README.md). From a43344b457dc3ddd38ec463b1dd294fb7b938d58 Mon Sep 17 00:00:00 2001 From: Yuma Takino <36617106+tappe9@users.noreply.github.com> Date: Wed, 2 Sep 2026 14:13:13 +0900 Subject: [PATCH 10/10] test(docs): preserve existing documentation safeguards --- scripts/test-public-documentation.py | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/scripts/test-public-documentation.py b/scripts/test-public-documentation.py index 11d7e09..4c21609 100644 --- a/scripts/test-public-documentation.py +++ b/scripts/test-public-documentation.py @@ -11,6 +11,10 @@ REQUIRED_SNIPPETS = { "README.md": [ "`pgdumpx 0.2.0` is published on crates.io", + "## Installation", + "### CLI from crates.io", + "### Library from crates.io", + "### From source", "https://crates.io/crates/pgdumpx", "https://crates.io/crates/pgdumpx-cli", "https://docs.rs/pgdumpx/0.2.0/pgdumpx/", @@ -23,6 +27,10 @@ ], "README.ja.md": [ "`pgdumpx 0.2.0`はcrates.ioで公開済みです", + "## インストール", + "### crates.ioからCLIをinstall", + "### crates.ioからlibraryを利用", + "### ソースから", "https://crates.io/crates/pgdumpx", "https://crates.io/crates/pgdumpx-cli", "https://docs.rs/pgdumpx/0.2.0/pgdumpx/", @@ -36,6 +44,11 @@ "ROADMAP.md": [ "Status: **v0.2.0 released", "## v0.2 — Completed and released", + "### Delivered", + "#57–#63", + "#70–#78", + "#89", + "#92", "https://crates.io/crates/pgdumpx/0.2.0", "https://crates.io/crates/pgdumpx-cli/0.2.0", "https://github.com/tappe9/pgdumpx/releases/tag/v0.2.0", @@ -53,6 +66,8 @@ "Security fixes target the latest published 0.2.x release and the current `main` branch.", "https://crates.io/crates/pgdumpx", "https://github.com/tappe9/pgdumpx/releases", + "## Dependency advisory policy", + "## Fuzzing", ], "CONTRIBUTING.md": [ "python3 scripts/test-public-documentation.py", @@ -89,21 +104,29 @@ "Check the exact versions before installing", "v0.2 is planned", "no v0.2 production code has merged yet", + "**Planned next:** v0.2", ], "README.ja.md": [ "registry commandを使うには、対象package versionがcrates.ioに存在する必要があります", "crates.ioでpackage versionを確認してから", + "v0.2は[Tracking Issue #56]", "v0.2のproduction codeはまだ`main`へmergeされていません", + "**次に実装するv0.2:**", ], "ROADMAP.md": [ "the 0.2.0 publication process is tracked separately from source delivery", "this roadmap does not infer their live state", "## v0.2 candidate", + "No production implementation exists yet", + ], + "docs/API-DESIGN.md": [ + "The current repository is still in the design phase", ], "SECURITY.md": [ "If no package has been published yet", "when one exists", "pgdumpx has no published release version yet", + "## Current v0.1 scope boundary", ], "docs/PACKAGING.md": [ "registry publication pending credentials",