Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
67 lines (48 loc) · 3.9 KB

CONTRIBUTING.md

File metadata and controls

67 lines (48 loc) · 3.9 KB
Raw

Contributing to SpecifyX

Hi there! We're thrilled that you'd like to contribute to SpecifyX. Contributions to this project are released to the public under the project's open source license.

Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.

Prerequisites for running and testing code

These are one time installations required to be able to test your changes locally as part of the pull request (PR) submission process.

  1. Install Python 3.11+
  2. Install uv for package management
  3. Install Git
  4. Have an AI coding agent available: Claude Code, GitHub Copilot, or Gemini CLI

Submitting a pull request

  1. Fork and clone the repository
  2. Configure and install the dependencies: uv sync
  3. Make sure the CLI works on your machine: uv run specifyx --help
  4. Create a new branch: git checkout -b my-branch-name
  5. Make your change, add tests, and make sure everything still works
  6. Test the CLI functionality with a sample project if relevant
  7. Push to your fork and submit a pull request
  8. Wait for your pull request to be reviewed and merged.

Here are a few things you can do that will increase the likelihood of your pull request being accepted:

  • Follow the project's coding conventions.
  • Write tests for new functionality.
  • Update documentation (README.md, spec-driven.md) if your changes affect user-facing features.
  • Keep your change as focused as possible. If there are multiple changes you would like to make that are not dependent upon each other, consider submitting them as separate pull requests.
  • Write a good commit message.
  • Test your changes with the Spec-Driven Development workflow to ensure compatibility.

Development workflow

When working on SpecifyX:

  1. Test changes with the specifyx CLI commands (run specifyx --help to see available commands)
  2. Test commands with your coding agent of choice when you create a sample project
  3. All templates are in src/specify_cli/templates/ directory

Documentation Strategy

SpecifyX uses a hybrid documentation approach with manually maintained guides and auto-generated API reference documentation:

  • User guides: Located in docs/docs/guides/ - manually maintained tutorials and how-to guides
  • Contributing guides: Located in docs/docs/contributing/ - manually maintained development guidelines
  • API reference: Located in docs/docs/reference/ - auto-generated from source code using docs/scripts/generate-metadata.py

The API reference documentation is automatically generated from Python docstrings, type hints, and code structure. This ensures the reference documentation stays current with code changes without manual maintenance.

When contributing:

  • Edit user guides and contributing docs directly in docs/docs/ directory
  • Do NOT edit files in docs/docs/reference/ - these are auto-generated
  • Write comprehensive docstrings in your code - they will appear in the auto-generated API docs
  • Regenerate API docs locally: cd docs && pnpm dev or pnpm generate (CI auto-syncs during builds)
  • Use pnpm generate:watch for continuous regeneration during development
  • Focus on clear, actionable content in both docstrings and manual documentation

Resources