Contributing to create-awesome-python-app

1Extension Structure

An extension typically consists of files that will be added to or modified in a template. Here's a recommended structure:

extensions/
└── your-extension-name/
    ├── files/           # Files to be added to or merged into the template
    ├── pyproject/       # Optional dependency fragments for pyproject.toml merge
    ├── extension.json   # Metadata, compatibility, and merge rules
    └── README.md        # Extension documentation

2Adding Your Extension to templates.json

Each extension must be registered in the templates.json file:

{
  "extensions": [
    // ... existing extensions
    {
      "name": "Your Extension Name",
      "slug": "your-extension-name",
      "description": "A concise description of your extension",
      "url": "https://github.com/Create-Python-App/cpa-templates/tree/main/extensions/your-extension-name",
      "type": ["template-type1", "template-type2"],
      "category": "Extension Category",
      "labels": ["Label1", "Label2", "Label3"]
    }
  ]
}

Here's what each property means:

• name: The display name of your extension
• slug: A unique identifier for your extension (URL-friendly)
• description: A brief description of what your extension offers
• url: The URL to your extension in the repository
• type: The type(s) of templates this extension is compatible with (string or array of strings)
• category: The category of the extension (e.g., "containers", "database", "observability", "security", "ci")
• labels: Keywords that describe your extension

3Creating an Extension

Follow these steps to create a new extension:

1. Identify the need: Determine what functionality you want to add to existing templates.
2. Create the extension files: Prepare the files that will be added to or modified in the template.
3. Define dependencies: Declare Python packages your extension adds in a pyproject/ fragment or equivalent merge file consumed by the CLI.
4. Add scripts or tasks: If your extension needs Makefile targets or documented uv run commands, include them in the extension README and any task runner config.
5. Document your extension: Create a README.md that explains how to use your extension and what it provides.

# Example pyproject dependency fragment (conceptual)
[project]
dependencies = [
  "httpx>=0.27",
  "sqlalchemy>=2.0",
]

[dependency-groups]
dev = [
  "pytest-cov>=5.0",
]

4Ensuring Compatibility

Extensions must be compatible with the templates they're designed for. Here's how to ensure compatibility:

• Specify compatible template types: In your extension's entry in templates.json, list all compatible template types in the type property.
• Test with all compatible templates: Verify that your extension works correctly with all the template types you've specified.
• Handle template variations: If templates have different structures (e.g., with or without a src directory), make your extension adaptable.

// Example of specifying multiple compatible template types
"type": ["fastapi-backend", "django-backend", "cli-app"]

5Submitting Your Extension

The process for submitting an extension is similar to submitting a template:

1. Fork the repository: Create a fork of the cpa-templates repository on GitHub.
2. Add your extension: Place your extension in the extensions/ directory.
3. Update templates.json: Add your extension to the templates.json file as described above.
4. Create a pull request: Submit a pull request with a clear description of your extension.