Skip to content

FORK.md

Latest commit

 

History

History
125 lines (91 loc) · 4.29 KB

FORK.md

File metadata and controls

125 lines (91 loc) · 4.29 KB

AppFolio Spec Kit Fork (specify-af-cli)

This is AppFolio's fork of github/spec-kit. It bundles AppFolio-specific extensions into the CLI for zero-config developer setup.

What's Changed from Upstream

Area Change
Package name specify-cli → specify-af-cli
Binary name specify → specify-af
Catalog URL Points at appfolio/spec-kit af-main branch
Init flow Auto-installs bundled AF extensions after scaffold
New command specify-af upgrade — syncs AF extensions to bundled versions
Version resolution Uses packages_distributions() instead of hardcoded package name
Release workflow release-please with af-v* tags on af-main
Install branch af-stable — only updated on release, safe for end-user installs

Installing

End users should install from the af-stable branch, which only updates when a release is tagged:

uv tool install git+https://github.com/appfolio/spec-kit@af-stable --force

To upgrade to the latest release:

uv tool install git+https://github.com/appfolio/spec-kit@af-stable --force --reinstall

Conflict-Prone Files

When merging upstream releases, expect conflicts in these files:

  • pyproject.toml — keep AF name, console script, and force-include entries
  • src/specify_cli/__init__.py — keep version fix (_get_distribution_name), init hook (install_af_extensions), upgrade command, panel title
  • src/specify_cli/extensions.py — keep AF catalog URL
  • src/specify_cli/presets.py — keep AF package name in error message
  • extensions/catalog.json — keep AF entries and catalog URL
  • .github/workflows/release.yml — keep af-v* tag filter, AF install URL, extension ZIP step

Fork Baseline

The fork diverged from upstream at commit 43cb0fa (feat: add bundled lean preset with minimal workflow commands (#2161)). When integrating an upstream release:

  1. Squash work commits into logical groups and drop release commits (their info lives in git tags and FORK.md changelog)
  2. Rebase onto the upstream tag
  3. Resolve conflicts (see Conflict-Prone Files above)
  4. Update the baseline commit below after completing the integration

Current baseline: 43cb0fa — feat: add bundled lean preset with minimal workflow commands (#2161)

How to Maintain

Local Development Setup

git clone git@github.com:appfolio/spec-kit.git
cd spec-kit
git checkout af-main
uv tool install . --force
specify-af version

Making Changes

git checkout -b feat/my-feature af-main
# Make changes (use Conventional Commits: feat:, fix:, chore:, etc.)
uv tool install . --force --reinstall
cd /path/to/test-project && specify-af init --here --ai claude
git push -u origin feat/my-feature
# Open PR targeting af-main

Adding a New AF Extension

  1. Create extensions/af-<name>/ with extension.yml, README.md, commands/
  2. Add "af-<name>" to AF_EXTENSION_IDS in src/specify_cli/af_init.py
  3. Add "extensions/af-<name>" = "specify_cli/core_pack/extensions/af-<name>" to force-include in pyproject.toml
  4. Add entry to extensions/catalog.json

Integrating an Upstream Release

git fetch upstream --tags
git checkout af-main
git merge v<upstream-version>
# Resolve conflicts (see Conflict-Prone Files above)
# Test: uv tool install . --force --reinstall && specify-af init --here

If integration work is needed:

git checkout -b feat/integrate-v<version>
# Fix, test, open PR to af-main

Release History

0.6.1.4 (2026-04-11)

  • feat: add af-stable branch for end-user installs

0.6.1.3 (2026-04-11)

  • docs: add CLAUDE.md with fork strategy and testing
  • docs: add FORK.md with maintenance guide and baseline
  • test: add AF extension to inventory test expectations
  • feat: add bundled AF extension with auto-install
  • feat: fork infrastructure — specify-af-cli
  • fix: skip docs deployment workflow on forks (#2171)
  • chore: release 0.6.1, begin 0.6.2.dev0 development (#2162)

0.6.1.2 (2026-04-11)

  • docs: add CLAUDE.md with fork strategy and git rules
  • feat: AppFolio spec-kit fork — specify-af-cli with bundled extensions

0.6.1.1 (2026-04-11)

  • feat: AppFolio spec-kit fork — specify-af-cli with bundled extensions