Skip to content

1.0 stability and backwards-compatibility policy #65

Description

@joshrotenberg

Problem

Tinfoil is at 0.2.10. Features have stabilized (19 audit issues
closed, full dogfood loop proven), but there's no explicit statement
of what users can rely on post-1.0 vs what might still change.

Before cutting 1.0, commit to what's stable and what isn't, so
downstream users know what they're signing up for.

Fix

Add a `CONTRIBUTING.md` (or README section) covering:

Stable surface:

  • The `:tinfoil` config keyword schema (all keys documented in
    README today)
  • The generated workflow template shape (matrix entry keys, job
    names, artifact names)
  • The public modules and functions documented in `@doc` (config
    loading, plan building, build/publish/homebrew mix tasks, target
    specs)
  • The on-disk artifact layout (`tar.gz` + `.sha256` pairs, combined
    `checksums-sha256.txt`)

Not stable:

  • Internal module boundaries and function arities not in `@doc`
  • The EEx template file structure (users shouldn't import from them)
  • Error atom shapes inside `{:error, term}` tuples; the
    `format_error/1` rendering stays stable but the internal
    representation may change

Deprecation mechanism:

  • How a config key gets renamed or removed: one minor-version warning
    cycle before removal
  • How a runner default changes: documented migration, existing users
    can pin via `:extra_targets`

Acceptance

  • Policy lives in `CONTRIBUTING.md` or the README
  • Linked from the top of the README so users see it before adopting
  • Closes out the 1.0 readiness checklist

Metadata

Metadata

Assignees

No one assigned

    Labels

    type:docsDocumentation and developer-facing prose

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions