Prepare v0.3.0 release (#24)

Release-prep changes for v0.3.0: version bump, changelog, docs, and
gitignore.

## Changes

- **Version bump** `0.2.0` → `0.3.0` in workspace `Cargo.toml` and all
path-dependency pins (`buffa-build`, `buffa-codegen`,
`protoc-gen-buffa`, `protoc-gen-buffa-packaging`).
- **CHANGELOG.md**: cut the `[0.3.0]` section from `[Unreleased]` and
added entries for #7 (proto comments → rustdoc), #8 (`buffa-descriptor`
crate), #15 (`clippy::use_self`), #17 (write-if-changed), #20
(synthetic-oneof collision fix), #21 (`MAX_FIELD_NUMBER`), plus a
placeholder `#TBD` for the rustdoc sanitization fix. The
extensions/textproto/TypeRegistry entries were already present.
- **README.md**: updated version pin example to `0.3`; reworded the
reflection bullet now that `buffa-descriptor` exists as a published
crate.
- **docs/guide.md**: updated all `0.1`/`v0.2.0` version strings to
`0.3`/`v0.3.0`.
- **.gitignore**: added `benchmarks/datasets/hyperpb/`.

## Dependencies

This PR should land **after** the rustdoc sanitization fix (PR #25,
merged) so the v0.3.0 tag has a working docs.rs build. Once that PR
merges, the `#TBD` placeholder in CHANGELOG.md should be replaced with
its real number before this is merged.

## Publish notes

`buffa-descriptor` is a **new** crate in this release. crates.io has no
pending-publisher mechanism, so its first publish via the tag-triggered
`publish-crates.yml` workflow will fail OIDC auth. Set
`CARGO_REGISTRY_TOKEN` in the repo secrets before tagging (or rerun the
failed job after setting it — the workflow is idempotent), then
configure Trusted Publishing on crates.io for subsequent releases.

## Checklist

- [x] `task lint` clean
- [x] `task test` passing
- [x] `task lint-md` clean
- [x] `cargo metadata` shows all workspace crates at 0.3.0
- [x] Replace `#TBD` in CHANGELOG.md with the rustdoc-fix PR number

Author: iainmcgin

.github/workflows/release.yml

@@ -1,6 +1,6 @@
 name: Release protoc plugins
 
-# Triggered by pushing a tag like v0.2.0.
+# Triggered by pushing a tag matching v*.
 # Builds protoc-gen-buffa and protoc-gen-buffa-packaging for
 # Linux (x86_64, aarch64), macOS (x86_64, aarch64), and Windows (x86_64).
 # Creates a GitHub release with the binaries, SHA-256 checksums,

.gitignore

@@ -7,6 +7,7 @@ conformance/target-nostd/
 target/
 benchmarks/results/
 benchmarks/charts/__pycache__/
+benchmarks/datasets/hyperpb/
 
 # Stress test output
 stress/googleapis/out/

CHANGELOG.md

@@ -6,6 +6,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-04-01
+
 ### Breaking changes
 
 - **`Extension::new(number)` → `Extension::new(number, extendee)`.** Same for
@@ -61,6 +63,39 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
   text-format conformance suite (883/883).
 - **Conformance:** `TestAllTypesEdition2023` enabled; binary+JSON 5539 → 5549
   passing (std). Text format suite 0 → 883 passing (was entirely skipped).
+- **`buffa-descriptor` crate** — `FileDescriptorProto` and friends are now in a
+  standalone crate that depends only on `buffa`, so descriptor types are usable
+  without pulling in `quote`/`syn`/`prettyplease`. `buffa-codegen` re-exports
+  the module so existing `buffa_codegen::generated::*` paths still resolve.
+  ([#8](https://github.com/anthropics/buffa/pull/8))
+- **Proto source comments → rustdoc.** Comments from `.proto` files are now
+  emitted as `///` doc comments on generated structs, fields, enums, variants,
+  and view types. Requires `--include_source_info` (set automatically by
+  `buffa-build` and the protoc plugins).
+  ([#7](https://github.com/anthropics/buffa/pull/7))
+- **`buffa::encoding::MAX_FIELD_NUMBER`** constant (`(1 << 29) - 1`), replacing
+  the magic number at all call sites.
+  ([#21](https://github.com/anthropics/buffa/pull/21))
+
+### Changed
+
+- **`buffa-build` skips writing unchanged outputs**, avoiding mtime bumps that
+  trigger needless downstream recompilation.
+  ([#17](https://github.com/anthropics/buffa/pull/17))
+- **Generated code emits `Self`** in `impl` blocks instead of repeating the
+  type name, so consumer crates that enable `clippy::use_self` get clean
+  output. ([#15](https://github.com/anthropics/buffa/pull/15))
+
+### Fixed
+
+- **Codegen no longer reports a false name collision** between a nested type
+  and a proto3 `optional` field whose synthetic oneof PascalCases to the same
+  name. ([#20](https://github.com/anthropics/buffa/pull/20),
+  fixes [#12](https://github.com/anthropics/buffa/issues/12))
+- **Generated rustdoc no longer breaks on proto comments** containing
+  `[foo][]` reference-style links or bare URLs — these are now escaped so
+  rustdoc treats them as literal text.
+  ([#25](https://github.com/anthropics/buffa/pull/25))
 
 ## [0.2.0] - 2026-03-16
 
@@ -187,6 +222,7 @@ This release publishes:
 
 MSRV: Rust 1.85.
 
-[Unreleased]: https://github.com/anthropics/buffa/compare/v0.2.0...HEAD
+[Unreleased]: https://github.com/anthropics/buffa/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/anthropics/buffa/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/anthropics/buffa/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/anthropics/buffa/releases/tag/v0.1.0

Cargo.lock

@@ -22,7 +22,7 @@ exclude = [
 ]
 
 [workspace.package]
-version = "0.2.0"
+version = "0.3.0"
 edition = "2021"
 rust-version = "1.85"
 license = "Apache-2.0"
@@ -31,12 +31,12 @@ keywords = ["protobuf", "protocol-buffers", "serialization", "no-std", "editions
 categories = ["encoding", "no-std"]
 
 [workspace.dependencies]
-buffa = { path = "buffa", version = "0.2.0", default-features = false }
-buffa-types = { path = "buffa-types", version = "0.2.0" }
-buffa-descriptor = { path = "buffa-descriptor", version = "0.2.0" }
-buffa-codegen = { path = "buffa-codegen", version = "0.2.0" }
-buffa-build = { path = "buffa-build", version = "0.2.0" }
-buffa-test = { path = "buffa-test", version = "0.2.0" }
+buffa = { path = "buffa", version = "0.3.0", default-features = false }
+buffa-types = { path = "buffa-types", version = "0.3.0" }
+buffa-descriptor = { path = "buffa-descriptor", version = "0.3.0" }
+buffa-codegen = { path = "buffa-codegen", version = "0.3.0" }
+buffa-build = { path = "buffa-build", version = "0.3.0" }
+buffa-test = { path = "buffa-test", version = "0.3.0" }
 base64 = { version = "0.22", default-features = false, features = ["alloc"] }
 bytes = { version = "1", default-features = false }
 hashbrown = { version = "0.15", default-features = false, features = ["default-hasher"] }

Cargo.toml

@@ -1,5 +1,13 @@
 # buffa
 
+[![crates.io](https://img.shields.io/crates/v/buffa.svg)](https://crates.io/crates/buffa)
+[![docs.rs](https://img.shields.io/docsrs/buffa)](https://docs.rs/buffa)
+[![CI](https://github.com/anthropics/buffa/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/anthropics/buffa/actions/workflows/ci.yml)
+[![MSRV](https://img.shields.io/crates/msrv/buffa)](Cargo.toml)
+[![deps.rs](https://deps.rs/repo/github/anthropics/buffa/status.svg)](https://deps.rs/repo/github/anthropics/buffa)
+[![no_std](https://img.shields.io/badge/no__std-compatible-blue)](docs/guide.md#no_std-usage)
+[![License](https://img.shields.io/crates/l/buffa)](LICENSE)
+
 A pure-Rust Protocol Buffers implementation with first-class [protobuf editions](https://protobuf.dev/editions/overview/) support. Written by Claude ❣️
 
 ## Why buffa?
@@ -36,7 +44,7 @@ buffa supports **binary**, **JSON**, and **text** protobuf encodings:
 
 These are intentionally out of scope:
 
-- **Runtime reflection** (`DynamicMessage`, descriptor-driven introspection) — not planned for 0.1. Buffa is a codegen-first library; if you need schema-agnostic processing, consider preserving unknown fields or using `Any`.
+- **Runtime reflection** (`DynamicMessage`, descriptor-driven introspection) — planned for a future release. The descriptor types are now available in `buffa-descriptor` as a first step. Buffa remains a codegen-first library; if you need schema-agnostic processing today, consider preserving unknown fields or using `Any`.
 - **Proto2 optional-field getter methods** — `[default = X]` on `optional` fields does not generate `fn field_name(&self) -> T` unwrap-to-default accessors. Custom defaults are applied only to `required` fields via `impl Default`. Optional fields are `Option<T>`; use pattern matching or `.unwrap_or(X)`.
 - **Scoped `JsonParseOptions` in `no_std`** — serde's `Deserialize` trait has no context parameter, so runtime options must be passed through ambient state. In `std` builds, [`with_json_parse_options`] provides per-closure, per-thread scoping via a thread-local. In `no_std` builds, [`set_global_json_parse_options`] provides process-wide set-once configuration via a global atomic. The two APIs are mutually exclusive. The `no_std` global supports singular-enum accept-with-default but not repeated/map container filtering (which requires scoped strict-mode override).
 
@@ -52,7 +60,7 @@ These are gaps we intend to address in future releases:
 
 ## Semver and API stability
 
-Buffa is pre-1.0. We follow the [Rust community convention](https://doc.rust-lang.org/cargo/reference/semver.html) for 0.x crates: breaking changes increment the **minor** version (0.1.x → 0.2.0), additive changes increment the **patch** version (0.1.0 → 0.1.1). Pin to a minor version (`buffa = "0.1"`) to avoid surprises.
+Buffa is pre-1.0. We follow the [Rust community convention](https://doc.rust-lang.org/cargo/reference/semver.html) for 0.x crates: breaking changes increment the **minor** version (0.1.x → 0.2.0), additive changes increment the **patch** version (0.1.0 → 0.1.1). Pin to a minor version (`buffa = "0.3"`) to avoid surprises.
 
 The generated code API (struct shapes, `Message` trait, `MessageView` trait, `EnumValue`, `MessageField`) is considered the primary stability surface. Internal helper modules marked `#[doc(hidden)]` (`__private`, `__buffa_*` fields) may change at any time.
 
@@ -146,12 +154,12 @@ Throughput comparison across four representative message types, measured on an I
 
 <details><summary>Raw data (MiB/s)</summary>
 
-| Message | buffa | buffa (view) | prost | protobuf‑v4 | Go |
-|---------|------:|-------------:|------:|------------:|---:|
-| ApiResponse | 762 | 1,245 (+63%) | 777 (+2%) | 720 (−5%) | 277 (−64%) |
-| LogRecord | 689 | 1,772 (+157%) | 692 (+0%) | 882 (+28%) | 251 (−64%) |
-| AnalyticsEvent | 188 | 307 (+63%) | 258 (+37%) | 364 (+93%) | 92 (−51%) |
-| GoogleMessage1 | 801 | 1,093 (+36%) | 1,001 (+25%) | 659 (−18%) | 351 (−56%) |
+| Message | buffa | buffa (view) | prost | protobuf-v4 | Go |
+|---------|------:|------:|------:|------:|------:|
+| ApiResponse | 834 | 1,413 (+69%) | 766 (−8%) | 712 (−15%) | 270 (−68%) |
+| LogRecord | 768 | 1,921 (+150%) | 681 (−11%) | 873 (+14%) | 249 (−68%) |
+| AnalyticsEvent | 198 | 316 (+60%) | 252 (+28%) | 358 (+81%) | 91 (−54%) |
+| GoogleMessage1 | 1,024 | 1,322 (+29%) | 998 (−3%) | 648 (−37%) | 344 (−66%) |
 
 </details>
 
@@ -161,12 +169,12 @@ Throughput comparison across four representative message types, measured on an I
 
 <details><summary>Raw data (MiB/s)</summary>
 
-| Message | buffa | prost | protobuf‑v4 | Go |
-|---------|------:|------:|------------:|---:|
-| ApiResponse | 2,637 | 1,755 (−33%) | 1,050 (−60%) | 570 (−78%) |
-| LogRecord | 4,149 | 3,163 (−24%) | 1,717 (−59%) | 309 (−93%) |
-| AnalyticsEvent | 671 | 369 (−45%) | 516 (−23%) | 162 (−76%) |
-| GoogleMessage1 | 2,543 | 1,866 (−27%) | 882 (−65%) | 366 (−86%) |
+| Message | buffa | prost | protobuf-v4 | Go |
+|---------|------:|------:|------:|------:|
+| ApiResponse | 2,613 | 1,680 (−36%) | 1,049 (−60%) | 556 (−79%) |
+| LogRecord | 4,102 | 3,000 (−27%) | 1,666 (−59%) | 302 (−93%) |
+| AnalyticsEvent | 656 | 366 (−44%) | 511 (−22%) | 159 (−76%) |
+| GoogleMessage1 | 2,644 | 1,867 (−29%) | 872 (−67%) | 358 (−86%) |
 
 </details>
 
@@ -178,10 +186,10 @@ Throughput comparison across four representative message types, measured on an I
 
 | Message | buffa | prost | Go |
 |---------|------:|------:|---:|
-| ApiResponse | 869 | 776 (−11%) | 119 (−86%) |
-| LogRecord | 1,335 | 1,099 (−18%) | 144 (−89%) |
-| AnalyticsEvent | 781 | 768 (−2%) | 52 (−93%) |
-| GoogleMessage1 | 1,047 | 840 (−20%) | 129 (−88%) |
+| ApiResponse | 867 | 805 (−7%) | 116 (−87%) |
+| LogRecord | 1,312 | 1,083 (−17%) | 140 (−89%) |
+| AnalyticsEvent | 777 | 758 (−2%) | 51 (−93%) |
+| GoogleMessage1 | 1,021 | 830 (−19%) | 128 (−88%) |
 
 </details>
 
@@ -193,10 +201,10 @@ Throughput comparison across four representative message types, measured on an I
 
 | Message | buffa | prost | Go |
 |---------|------:|------:|---:|
-| ApiResponse | 721 | 299 (−59%) | 71 (−90%) |
-| LogRecord | 780 | 694 (−11%) | 112 (−86%) |
-| AnalyticsEvent | 272 | 239 (−12%) | 47 (−83%) |
-| GoogleMessage1 | 635 | 253 (−60%) | 74 (−88%) |
+| ApiResponse | 718 | 293 (−59%) | 70 (−90%) |
+| LogRecord | 797 | 690 (−13%) | 110 (−86%) |
+| AnalyticsEvent | 265 | 235 (−11%) | 46 (−83%) |
+| GoogleMessage1 | 646 | 255 (−60%) | 73 (−89%) |
 
 </details>