Skip to content

Conversation

danwashusen
Copy link

@danwashusen danwashusen commented Sep 20, 2025

Summary

  • Introduces an offline/local template flow via SPECIFY_TEMPLATE_ZIP and adds ignore rules for
    generated artifacts.
  • Consolidates and expands Local Development documentation into a single guide.

Included commits

  • 9c8cea9: Add .gitignore rules, document local build/install steps, implement SPECIFY_TEMPLATE_ZIP
  • eff3c72: Refactor build/development instructions to docs/local-development.md; update CONTRIBUTING
    and README

What changed

  • CLI
    • Add SPECIFY_TEMPLATE_ZIP support to bypass GitHub download and use a local template ZIP, with
      safe cleanup behavior.
      • src/specify_cli/init.py:548
      • src/specify_cli/init.py:559
  • Docs
    • Move “Development workflow” content into a dedicated Local Development guide and expand with an
      offline packaging flow:
      • docs/local-development.md:1
      • docs/local-development.md:96
      • docs/local-development.md:121
    • Point CONTRIBUTING to the Local Development guide:
      • CONTRIBUTING.md:39
    • Link README to the guide (ToC + Learn More):
      • README.md:26
      • README.md:254
  • Repo hygiene
    • Ignore local build outputs:
      • .gitignore:1

How to use (quick)

  • Build local templates:
    • Linux:
      • chmod +x .github/workflows/scripts/create-release-packages.sh && .github/workflows/scripts/
        create-release-packages.sh v0.0.1 && chmod -x .github/workflows/scripts/create-release-packages.sh
    • macOS (Docker):
      • docker run --rm -it -v "$PWD":/w -w /w ubuntu:24.04 bash -lc "apt-get update && apt-get
        install -y zip && chmod +x .github/workflows/scripts/create-release-packages.sh && .github/workflows/
        scripts/create-release-packages.sh v0.0.1 && chmod -x .github/workflows/scripts/create-release-
        packages.sh"
  • Run CLI against a local ZIP:
    • SPECIFY_TEMPLATE_ZIP=/abs/path/spec-kit-template--<script>-v0.0.1.zip uvx --refresh --no-
      cache --from /abs/path/to/spec-kit specify init --here --ai --script <script> --ignore-agent-
      tools

Why

  • Enables fully offline testing, avoids API rate limits/corporate proxy issues, and speeds iteration
    on template changes.
  • Reduces docs duplication between CONTRIBUTING and user-facing docs.

Verification

  • Build a ZIP with the packaging script; confirm artifacts are produced and git-ignored.
  • Run init with SPECIFY_TEMPLATE_ZIP; confirm the project initializes from the local archive and the
    file is not deleted on cleanup.
  • Confirm README and CONTRIBUTING links resolve to docs/local-development.md.

Impact

  • Backwards compatible; default behavior unchanged when SPECIFY_TEMPLATE_ZIP is not set.
  • Documentation improvements only outside of the env-var feature.

@danwashusen danwashusen changed the title Docs: Consolidate Local Development workflow, add packaging flow, and link from README Local Dev: offline template override (SPECIFY_TEMPLATE_ZIP) and consolidate development docs Sep 20, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

1 participant