Back to the guide

Maintaining Compony

Conventions for contributors and AI assistants working on the gem itself (not apps using it). Keeps docs, gemspec and the rendered API reference from drifting.

Every change

  • Behavior change → CHANGELOG. Add a bullet under the top # unreleased heading in CHANGELOG.md. If it breaks existing apps, add a ## Steps to take subsection with the migration (see prior entries for the format).
  • New/renamed DSL method → docs. Update dsl_reference.md (keep the # DSL method source marker) and add a YARD summary with @param/@return/@api on the method.
  • Comments only / docs only is fine to note as such in the CHANGELOG ("no behavior change").

Releasing

  1. Bump the version in lib/compony/version.rb. Loading the Rakefile rewrites VERSION from it; .edge marks an unreleased prerelease.
  2. Run rake gemspec — regenerates compony.gemspec (never hand-edit it; it says so).
  3. Move the # unreleased CHANGELOG block to a # X.Y.Z heading; start a fresh # unreleased.
  4. Run yard doc and commit the regenerated doc/*.html — the rendered API reference is committed and shipped in the gem (s.files), so stale HTML ships otherwise.
  5. bundle exec rubocop clean.
  6. Tag / push / gem build per your release flow (bundler/gem_tasks).

Dependencies

  • Hard deps and their constraints live only in the :gemspec task in Rakefile. Change them there, run rake gemspec, and update the mirror table in integrations.md in the same commit.
  • Keep the README's stated Rails/Ruby support in sync with required_ruby_version / the rails constraint — the gemspec is authoritative.

Documentation rendering

  • doc/*.html is generated by YARD from lib/ + the extra files listed in .yardopts.
  • Adding a guide page? Add its path to .yardopts (after the - separator) or it will not appear in the rendered reference, then re-run yard doc.
  • Markdown changes to already-listed guide pages still need a yard doc re-run + commit to refresh the HTML.
  • yard doc logs Cannot resolve link to … from text: for guide-to-guide Markdown links and inline <code> in the guide pages. This is expected and benign — YARD tries to treat them as Ruby code-object links. The pages render correctly and the links work on GitHub. Do not rewrite guide cross-links to silence YARD. (Genuine broken {Xref} in Ruby lib/ comments are worth fixing; guide-Markdown link warnings are not.)

Patterns derived from real apps

  • patterns.md / cookbook.md are fully anonymized: no app, business, author or domain-model names; neutral domain (Account, Order, LineItem, Document); app-wrapper-only APIs excluded or generalized (this is a public LGPL repo).
  • Document the secure variant only. Never reproduce an insecure shape (e.g. a capability token without expiry) even if that is what an app currently does — show the hardened form and call out the requirement.

Guide index