v1.0.0 — Initial Release

[jamesgober]

mod-tempdir — v1.0.0 Design Note: Stable API Declaration

Phase A output for the v1.0.0 milestone.

Goal

Declare the public API stable. From v1.0.0 onward, breaking changes
require a major-version bump per SemVer. The crate ships exactly the
surface that landed in v0.9.3. No new features, no removals, no
signature changes. v1.0.0 is the trust handshake, not new code.

What ships in 1.0.0

Pure stability declaration. The public API is identical to v0.9.3:

pub struct TempDir { /* private */ }
impl TempDir {
    pub fn new() -> io::Result<Self>;
    pub fn with_prefix(prefix: &str) -> io::Result<Self>;
    pub fn path(&self) -> &Path;
    pub fn persist(self) -> PathBuf;
    pub fn cleanup_on_drop(&self) -> bool;
}
impl Drop for TempDir { /* recursive cleanup */ }

pub struct NamedTempFile { /* private */ }
impl NamedTempFile {
    pub fn new() -> io::Result<Self>;
    pub fn with_prefix(prefix: &str) -> io::Result<Self>;
    pub fn path(&self) -> &Path;
    pub fn persist(self) -> PathBuf;
    pub fn persist_atomic(self, target: impl AsRef<Path>) -> Result<PathBuf, PersistAtomicError>;
    pub fn cleanup_on_drop(&self) -> bool;
}
impl Drop for NamedTempFile { /* remove_file */ }

pub struct PersistAtomicError { pub error: io::Error, pub file: NamedTempFile }
// + Debug + Display + std::error::Error + From<PersistAtomicError> for io::Error

pub fn cleanup_orphans(max_age_hours: u64) -> io::Result<usize>;

The default build still has zero runtime dependencies outside std.
The mod-rand feature flag remains the only opt-in surface.

Differences from v0.9.3 are limited to:

• Version number bumped to 1.0.0.
• README, REPS, ROADMAP, PROMPTS updated for the post-stability state.
• CHANGELOG rolled with a stability-declaration entry.
• The two audit-commit doc fixes from 1b890e9 (README
  cleanup-on-startup paragraph rewrite, PersistAtomicError
  rustdoc example) ship as part of an official cut for the first
  time. They have been on main since the audit but never reached
  crates.io.

Stability commitment

From this release forward:

• Breaking API changes require 2.0.0. Renames, signature
  changes that aren't purely additive, removed methods, removed
  types, and changes to documented Drop / persist semantics all
  count as breaking.
• Additive API changes (new methods on existing types, new free
  functions, new types) bump the minor version (1.1.0, 1.2.0,
  ...).
• Bug fixes, doc improvements, internal-only changes bump the
  patch version (1.0.1, 1.0.2, ...).
• MSRV stays at Rust 1.75 within the 1.x line. Any MSRV bump
  ships in a minor release with a notice; major MSRV changes wait
  for 2.0.
• The mod-rand feature flag is part of the stable surface. Its
  behavior (uniformly distributed Crockford base32 names via
  mod_rand::tier2::unique_name) is part of the contract.
• Default basename formats (.tmp-{pid}-{name12} for TempDir,
  .tmpfile-{pid}-{name12} for NamedTempFile) are part of the
  contract — they are what cleanup_orphans parses. Changing them
  would break callers that rely on either the format or the
  cleanup behaviour, and requires a major bump.

Explicitly out of scope for 1.0.0

• No new features. None ship in this cut.
• No API additions. Even purely-additive surface is deferred to
  1.1.0 so this release is unambiguously a stability signal.
• The fsys integration for atomic persistence is not revisited
  here; if it ever returns, it returns as additive minor work.

Verification (must hold at the version-bump boundary)

• 11/11 build matrix green: cargo build (default,
  --no-default-features, --features mod-rand, --all-features),
  cargo +1.75 build --all-features, cargo fmt --all -- --check,
  cargo clippy --all-targets --all-features -- -D warnings,
  cargo clippy --all-targets --no-default-features -- -D warnings,
  cargo test --all-features, cargo test --no-default-features,
  cargo doc --all-features --no-deps.
• 59 tests pass under --all-features (42 unit/integration + 17
  doctests).
• Banned-word + em-dash scan: zero hits across shipping files.
• Cross-platform test gating verified for #[cfg(windows)],
  #[cfg(target_os = "linux")], and feature gates.

Release ceremony

Standard pattern carried over from the 0.9.x line:

1. git tag -a v1.0.0 -m "Release v1.0.0 — stable API"
2. git push origin main
3. git push origin v1.0.0
4. cargo publish --dry-run --all-features
5. cargo publish
6. Confirm https://crates.io/crates/mod-tempdir/1.0.0 is live.

GitHub release title: v1.0.0 — stable API. Tagged as not-prerelease
for the first time.

---

Full Changelog: v0.9.3...v1.0.0

---

This discussion was created from the release v1.0.0 — Initial Release.