Skip to content

RELEASES.md

Latest commit

 

History

History
165 lines (133 loc) · 15.2 KB

RELEASES.md

File metadata and controls

165 lines (133 loc) · 15.2 KB

fusionAIze Gate Releases

This repo does not require a heavy release process. Use lightweight tags plus GitHub Releases, with release automation building the Python package and container image from tags.

Release Flow

  1. Make sure main is green.
  2. Update CHANGELOG.md:
    • Move the relevant notes from Unreleased into a versioned section.
    • Keep the notes focused on user-visible changes.
  3. Create an annotated tag from main.
  4. Push the tag to GitHub.
    • This is the trigger for the release pipeline: .github/workflows/release-artifacts.yml runs on push for tags matching v*.
  5. Let the release-artifacts workflow build Python distributions and the GHCR image.
  6. Create a GitHub Release from that tag.
    • The release title must be exactly fusionAIze Gate vX.Y.Z — notify-tap validates it and refuses to dispatch the Homebrew update otherwise. When using the gh CLI, always pass --title explicitly because some gh versions default the title to just the tag name (vX.Y.Z) when only --notes-from-tag is given.
    • Publishing the GitHub Release is the separate trigger for .github/workflows/notify-tap.yml. The same workflow also runs on edited, so a gh release edit --title on an existing release is enough to retroactively unblock the dispatch.
  7. Use the changelog entry as the release notes, then add any short upgrade notes if needed.
  8. Confirm that README plus the relevant docs pages still match the shipped runtime behavior.
  9. If packaging or Docker changed shortly before the release, run the publish dry run first.
  10. For hardening-heavy releases, keep the API functional tests green alongside unit and config coverage.
  11. Publish the GitHub Release so notify-tap can dispatch the Homebrew tap update automatically.
  12. If the tap dispatch fails or the formula needs manual follow-up, bump Formula/faigate.rb in the separate fusionAIze/homebrew-tap repo to the new release tag and update its sha256.
  13. For Anthropic bridge releases, run the client-near validation flow in docs/bridge/anthropic-bridge-release-readiness.md before tagging, and keep the feature positioned as opt-in unless a later release closes the documented parity gaps.

Example

git checkout main
git pull --ff-only origin main
git tag -a v1.8.0 -m "fusionAIze Gate v1.8.0"
git push origin v1.8.0

Then publish a GitHub Release for v1.8.0. From the CLI, always pass --title so the title matches the convention notify-tap enforces:

gh release create v1.8.0 \
  --title "fusionAIze Gate v1.8.0" \
  --notes-from-tag

If a release was already published with the wrong title, fix it in place — notify-tap re-runs on edited:

gh release edit v1.8.0 --title "fusionAIze Gate v1.8.0"

The tag push should trigger the release-artifacts bot automatically. Publishing the GitHub Release should then trigger the tap notification automatically. If the tap still needs a manual follow-up, use fusionAIze/homebrew-tap:

git clone https://github.com/fusionAIze/homebrew-tap.git
cd homebrew-tap
# update Formula/faigate.rb to the new tag and sha256
git commit -am "chore(formula): bump faigate to v1.8.0"
git push origin main

Automation Baseline

Tagged releases now trigger release-artifacts:

  • validate that the Git tag matches both pyproject.toml and faigate/__init__.py
  • always build sdist and wheel
  • run twine check dist/* before artifacts are uploaded or published
  • push the container image to GHCR
  • publish to PyPI only when PYPI_PUBLISH=true is set and GitHub trusted publishing is configured for the pypi environment
  • publish the already-built python-dist artifact to PyPI instead of rebuilding it in a second job

The repo also includes publish-dry-run:

  • build Python distributions without publishing them
  • run twine check
  • build the GHCR image without pushing it
  • exercise scripts/faigate-release --dry-run when release automation files change

Versioning Guidance

  • Use x.y.z version numbers and matching vx.y.z Git tags.
  • Use a patch bump for fixes, documentation polish, and small compatibility updates.
  • Use a minor bump for meaningful features, provider additions, routing behavior improvements, or operational changes.
  • Use a major bump only for explicit breaking changes with a documented migration path.
  • Avoid promising strict semantic versioning unless the project decides to enforce it consistently.

Current Release Baseline

  • v0.3.0 is the first fusionAIze Gate-branded release.
  • v0.4.0 establishes the hardened routing baseline: request hooks, multi-dimensional scoring, route introspection, and the refined operator dashboard.
  • v0.5.0 establishes the operator distribution baseline: image-provider contracts, Docker and GHCR packaging, PyPI workflow support, onboarding helpers, repo community standards, and cached release update checks.
  • v0.6.0 establishes the modality-expansion baseline: image route previews, provider capability coverage, shared image request validation, and image policy presets.
  • v0.7.0 establishes the operations-polish baseline: update alerts, operator events, rollout guardrails, scoped update checks, maintenance windows, and post-update verification hints.
  • v0.8.0 establishes the onboarding baseline: repeatable provider/client rollout helpers, starter templates, delegated-traffic examples, env validation, and shareable onboarding reports.
  • v0.9.0 is the pre-v1.0 hardening baseline: conservative response headers, bounded request surfaces, stronger functional API coverage, and a full documentation pass over operator-facing behavior.
  • v1.0.0 establishes the stable baseline: trust-boundary validation for upstream base URLs, sanitized provider-error responses, a documented security review, and the separate @faigate/cli npm package for CLI-facing workflows.
  • v1.1.0 deepens post-1.0 adoption: wider AI-native starter coverage, tighter policy semantics, richer client highlights in stats/dashboard, and cleaner onboarding guidance for popular agent frameworks.
  • v1.2.0 establishes the workstation and packaging baseline: Linux/macOS/Windows workstation guidance, macOS-aware runtime helpers, Windows startup examples, explicit config-path support for packaged installs, and a project-owned Homebrew formula path.
  • v1.2.1 is the first packaging follow-up on top of that baseline: the Homebrew formula now prefers python@3.12 for a cleaner macOS install path and the docs now explicitly cover unqualified brew install faigate after tapping the project-owned tap.
  • v1.2.2 hardens the macOS packaging path further: the Homebrew formula now builds pydantic-core from source with explicit header padding, validates the wrapped binary in its formula test, and documents how virtualenvs can shadow the Brew-installed CLI.
  • v1.2.3 finishes the immediate Brew runtime stabilization pass: the Brew-managed wrapper now invokes the correct Python module entrypoint and the formula also builds watchfiles from source to avoid the next macOS linkage fixup failure.
  • v1.3.0 establishes the guided setup and catalog-assisted discovery baseline: routing modes and shortcuts are first-class, the config wizard can suggest, diff, apply, and back up multi-provider changes, provider-catalog drift alerts are richer, and discovery views stay explicitly performance-led and link-neutral.
  • v1.4.0 establishes the rebrand baseline: the product name is now fusionAIze Gate, the technical slug is faigate, and package, script, service, documentation, and repository references align with the new identity.
  • v1.4.5 establishes the first Gate-native shell control-center baseline: operators now get one consistent menu for status, configure, clients, validation, control, and update flows, with client quickstarts, structured configure paths, and stronger service-control helpers.
  • v1.5.0 deepens that shell UX into a stronger happy path: Quick Setup, summary cards, client recommendation cards, drilldowns, and explicit next-step receipts now make first setup and handoff flows feel much more guided.
  • v1.5.1 polishes that guided shell UX: the wizard now surfaces compact ready-now candidate cards, the client area highlights the best next action more clearly, and base-url override prompts are explicitly framed as upstream provider overrides.
  • v1.6.0 establishes the operator decision-support baseline: provider setup, provider probe, client scenario templates, and the new shell dashboard now work together as one onboarding-and-operations flow, with budget and routing hints layered into the live metrics view.
  • v1.6.1 is the immediate packaging and polish follow-up: the Brew-installed dashboard helper is executable again, and the terminal wordmark now matches the intended shape more closely while surfacing the current version inline.
  • v1.6.2 is the immediate guided-setup recovery follow-up: wizard writes now persist actual runtime config, doctor can flag accidental suggestion payloads in config.yaml, and the remaining packaged helper entrypoints keep their executable bits in Brew installs.
  • v1.6.3 hardens that recovery line: nullish config sections no longer break guided writes, the missing Brew helper wrappers now match the shell UX more closely, and the refreshed three-color wordmark still surfaces the live version inline.
  • v1.7.0 establishes the internal-drilldown baseline: parameterized client, provider, and dashboard views now open directly inside Gate, and scenario templates explain provider roles and family coverage more explicitly instead of only listing flat recommendation sets.
  • v1.7.1 is the immediate polish follow-up: the wordmark now renders without accidental spacer gaps in interactive menus, and applying a client scenario cleanly returns control to the caller instead of repainting the same chooser screen.
  • v1.8.0 establishes the adaptive-lane-routing foundation: canonical model lanes, direct-versus-aggregator route metadata, same-lane-route fallback preference, early runtime pressure adaptation, and richer route explainability now shape both routing decisions and operator visibility.
  • v1.9.0 establishes the short-complex routing baseline: brief but risky opencode prompts now escape cheap fallthrough heuristics earlier, and route previews explain why cheaper alternatives lost on reasoning fit, freshness, or runtime pressure.
  • v1.10.0 establishes the cache- and hook-aware runtime baseline: provider-specific cache economics, community hook loading, and the first Grok bridge path now influence both routing cost estimates and extensibility.
  • v1.10.1 is the first v1.10 follow-up: the Grok adapter path and virtual-provider registration line are stable enough to ship as a public release.
  • v1.11.0 establishes the modern model-registry baseline: Gemini 3 / 3.1 lanes, dynamic model labels, and the first release-helper automation now move together instead of being hardcoded across the router, wizard, and catalog.
  • v1.11.2 is the release-reliability follow-up: Python 3.10 compatibility for the update helpers is restored and version surfaces are realigned so package metadata, CLI version output, and API version reporting stay in sync.
  • v1.12.0 establishes the operator-catalog baseline: provider-source drift is surfaced earlier, Kilo and BLACKBOX semantics are clearer, and release automation is boring and repeatable again.
  • v1.13.0 establishes the optional Anthropic bridge baseline: Claude-native clients can use an internal Anthropic-compatible surface, bridge traffic stays on the normal Gate routing core, and production rollout is supported as an explicitly opt-in feature line.

Planned Publishing Path

  • v0.3.x: GitHub Releases plus source checkout remain the default distribution path.
  • v0.5.0: Docker and PyPI publishing baseline is introduced through the release workflow and repo docs.
  • v0.6.0: modality-aware image routing becomes an explicit release line with provider inventory and image-policy guidance.
  • v0.7.0: helper-driven update controls become a first-class release line with scoped rollout gates and verification hooks.
  • v0.8.0: many-provider and many-client onboarding becomes copy/pasteable and validation-backed through reports, starters, and doctor checks.
  • v1.0.0: keep GitHub Releases, Docker, and PyPI, and add the separate npm CLI package under packages/faigate-cli.
  • v1.2.0: add the project-owned Homebrew packaging path for macOS workstations while keeping Docker, GitHub Releases, Python artifacts, and the separate npm CLI package.
  • v1.2.1: harden the Homebrew path with a more stable Python baseline and clearer tap/install guidance for macOS users.
  • v1.2.2: finish the first macOS packaging hardening pass by targeting the pydantic-core linkage warning directly and tightening the wrapper-level install checks.
  • v1.2.3: complete the immediate Brew-runtime stabilization work by fixing the packaged entrypoint path and broadening the native-wheel source-build policy on macOS.
  • v1.3.0: deepen guided onboarding and catalog-assisted operations with purpose-aware routing modes, config-wizard update flows, provider-catalog drift checks, and compact provider-discovery surfaces.
  • v1.4.0: ship the first fully rebranded release under fusionAIze/faigate so operators can adopt the new naming without mixed package, script, or documentation surfaces.
  • v1.4.5: ship the first cohesive shell UX line for standalone Gate operation, then follow with the actual Homebrew formula bump once the release tag exists.
  • v1.5.0: ship the first “guided wow path” for standalone Gate operation, then follow with the Homebrew formula bump once the release tag exists.
  • v1.5.1: tighten the first post-v1.5.0 UX follow-up with clearer wizard cards, client-action hints, and less ambiguous provider override prompts.

The npm package stays separate from the Python gateway core. It is meant for CLI-facing integrations, not for rewriting the service runtime.

v1.2.0 started the project-owned Homebrew path. The formula now lives in the separate fusionAIze/homebrew-tap repo instead of this runtime repo, which keeps release tagging and tap publishing loosely coupled.

Scheduled Deployment Examples

fusionAIze Gate now includes a conservative helper-driven update path for controlled environments. The recommended examples live in:

Use these only after you have already validated the manual path:

./scripts/faigate-update-check
./scripts/faigate-auto-update

Keep allow_major: false unless you are intentionally allowing major-version rollouts through the scheduled helper.

What Belongs In Release Notes

  • New providers or routing behavior changes
  • API surface changes
  • Deployment or operational changes
  • Breaking changes or migration notes
  • Fixes that affect request behavior, fallbacks, or observability