Skip to content

STABILITY.md

Latest commit

 

History

History
51 lines (39 loc) · 5.26 KB

STABILITY.md

File metadata and controls

51 lines (39 loc) · 5.26 KB
Raw

Stability

DevRail has reached v1.0 across all repositories. The core standards, toolchain, templates, and documentation are stable and in production use. This document tracks component status.

What "v1.0" Means

  • Backward compatibility. Breaking changes require a major version bump (v2.0.0). Minor and patch releases are additive.
  • Stable interfaces. Makefile targets, .devrail.yml schema, and CLI behavior are committed contracts.
  • New languages are additive. Adding a language ecosystem is a minor version bump — existing languages and behavior are unaffected.
  • Feedback is welcome. File issues, open discussions, or submit PRs.

Status by Component

Component Status Notes
Container image Stable Multi-arch (amd64 + arm64), signed with cosign, weekly rebuilds.
Makefile contract Stable Two-layer delegation pattern, JSON summary output, init scaffolding. As of v1.10.x the reference Makefile pins SHELL := /bin/bash so plugin libraries can be sourced directly into recipes; consumer template repos that inherit this Makefile require bash on the host (already the default on Debian/Ubuntu/macOS — only relevant for busybox/Alpine without bash).
Shell conventions Stable lib/log.sh, lib/platform.sh, header format, and idempotency patterns are settled.
Conventional commits Stable Types, scopes, and format are finalized. Pre-commit hook published.
Language standards Stable Python, Bash, Terraform, Ansible, Ruby, Go, JavaScript/TypeScript, Rust — all 8 ecosystems shipped.
Coding practices Stable General principles (DRY, KISS, testing, error handling) are finalized.
Git workflow Stable Branch strategy, PR process, and merge policy are finalized.
Release & versioning Stable Semver policy is defined and in use across all repos.
CI/CD pipelines Stable Stage contract defined. GitHub Actions and GitLab CI templates shipped.
Container standards Stable Guidelines are written.
Secrets management Stable Policy is defined. No custom tooling required.
API & CLI design Stable Guidelines are written. No custom tooling required.
Monitoring & observability Stable Guidelines are written. No custom tooling required.
Incident response Stable Process is defined. Templates are provided.
Data handling Stable Policy is defined. No custom tooling required.
CI workflow templates Stable GitHub Actions workflows and GitLab CI pipeline shipped in template repos.
Pre-commit hooks Stable Conventional commit hook and per-language hooks configured in template repos.
Documentation site Stable devrail.dev is live with full standards coverage.
Plugin loader + resolver + lockfile + build pipeline + execution loop Stable (v1.10.x baseline; reference plugin v1.11.x) Validates plugin.devrail.yml manifests, resolves rev: to immutable SHAs (make plugins-update), records reproducibility metadata in .devrail.lock, and auto-builds a project-local extended image (devrail-local:<hash>) when plugins are declared. Each loaded plugin's targets are dispatched inside _lint/_format/_fix/_test/_security with gate evaluation, {paths} interpolation, per-language overrides, and JSON aggregation into the existing event shape. DEVRAIL_FAIL_FAST=1 short-circuits on plugin failures the same as core. No-op when plugins: is absent — v1.9.x behaviour unchanged. As of v1.11.0 the first reference plugin (devrail-plugin-kotlin) is published; the extraction is additive through the v1.x line (Kotlin remains in core for back-compat). v2.0.0 retires the in-core HAS_ blocks.

Consumer responsibilities

These are services/data the dev-toolchain container does not provide; consumers must provide them when relevant:

  • Database service (Postgres, MySQL, etc.) — required for Rails projects whose specs touch the test database. The container runs bundle exec rails db:test:prepare before rspec (when config/application.rb + Gemfile are present), which needs a reachable database. Typical local pattern: docker-compose up -d postgres before make test. Typical CI pattern: a services: block.
  • Project bundle install — the container ships its own gems for rubocop/reek/etc. as defaults, but for Gemfile-pinned versions it expects the project's bundle to already be installed (bundle install) so bundle exec <tool> can find them.
  • Host tooling for plugin builds — when .devrail.yml declares plugins:, the host running make check must have Docker (with buildx), yq (v4+), sha256sum (coreutils), and flock (util-linux) available. No-op when plugins: is absent.

Versioning

All DevRail repos follow Semantic Versioning. The container image uses a floating major tag (:v1) that always points to the latest v1.x.x release. Pin to a specific tag (e.g., :v1.4.0) if you need exact reproducibility.

How to Track Changes

  • Watch the CHANGELOG.md in each repo for release-by-release details.
  • Breaking changes will be called out explicitly in changelog entries during beta.