From 69680c53e35ae9494595d0779bb575d1ea3d90f5 Mon Sep 17 00:00:00 2001 From: Jon Zeolla Date: Wed, 16 Jul 2025 12:59:29 -0400 Subject: [PATCH 1/4] docs(docs): add initial docs baseline --- .cursor/rules/python-template.mdc | 12 ++- .../{CONTRIBUTING.md => CODE_OF_CONDUCT.md} | 0 .github/copilot-instructions.md | 6 +- .github/etc/dictionary.txt | 7 ++ CLAUDE.md | 12 +-- CONTRIBUTING.md | 2 +- README.md | 12 +-- docs/ai-ide-support.md | 43 ++++++++++ docs/ci-cd.md | 50 +++++++++++ docs/configuration.md | 82 +++++++++++++++++++ FAQ.md => docs/faq.md | 13 +-- docs/hooks.md | 73 +++++++++++++++++ docs/index.md | 33 ++++++++ docs/optional-setup.md | 53 ++++++++++++ ROADMAP.md => docs/roadmap.md | 9 +- docs/testing.md | 61 ++++++++++++++ 16 files changed, 426 insertions(+), 42 deletions(-) rename .github/{CONTRIBUTING.md => CODE_OF_CONDUCT.md} (100%) create mode 100644 docs/ai-ide-support.md create mode 100644 docs/ci-cd.md create mode 100644 docs/configuration.md rename FAQ.md => docs/faq.md (83%) create mode 100644 docs/hooks.md create mode 100644 docs/index.md create mode 100644 docs/optional-setup.md rename ROADMAP.md => docs/roadmap.md (90%) create mode 100644 docs/testing.md diff --git a/.cursor/rules/python-template.mdc b/.cursor/rules/python-template.mdc index 1c6e8d0..04a7d69 100644 --- a/.cursor/rules/python-template.mdc +++ b/.cursor/rules/python-template.mdc @@ -7,17 +7,21 @@ type: always You are working on a cookiecutter template for generating modern Python projects. ## Critical Context -This is a TEMPLATE GENERATOR. Files in `{{cookiecutter.project_name}}/` contain Jinja2 variables that must be preserved exactly as written. + +This is a TEMPLATE GENERATOR. Files in `{{cookiecutter.project_name ...}}/` contain Jinja2 variables that must be preserved exactly as written. ## Tech Stack + - Python 3.13+ with uv package manager (NOT pip/poetry) - pytest with >80% coverage requirement - Pre-commit: ruff, pyright, refurb - Security: grype, syft - CI/CD: GitHub Actions -- Versioning: CalVer or SemVer-ish + +6. Update documentation in the docs/ directory as features are added or changed ## Code Standards + - Max line length: 120 - Type hints required - Google-style docstrings @@ -26,6 +30,7 @@ This is a TEMPLATE GENERATOR. Files in `{{cookiecutter.project_name}}/` contain - Specific exception handling ## Key Commands + ```bash task init # Setup environment task build # Build project @@ -34,7 +39,8 @@ task lint # Check code quality ``` ## Template Testing + ```bash -uvx cookiecutter . # Generate project +uvx --with gitpython cookiecutter . # Generate project pytest tests/ # Test template ``` diff --git a/.github/CONTRIBUTING.md b/.github/CODE_OF_CONDUCT.md similarity index 100% rename from .github/CONTRIBUTING.md rename to .github/CODE_OF_CONDUCT.md diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 3fc2e2d..1896f00 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -6,10 +6,8 @@ built-in. ## Context - This is a **template generator**, not a regular Python project -- Files in `{{cookiecutter.project_name}}` directory contain Jinja2 template variables +- Files in the `{{cookiecutter.project_name ... }}` directory contain Jinja2 template variables - The project uses `uv` as the package manager (not pip or poetry) -- Python 3.13+ is the minimum requirement -- The template uses python-semantic-release for automated versioning ## Code Conventions @@ -60,7 +58,7 @@ Common tasks are automated via Taskfile: 3. Follow the established project structure 4. Include appropriate error handling 5. Add tests for new functionality -6. Update documentation as needed +6. Update documentation in the docs/ directory as features are added or changed ## Template-Specific Guidelines diff --git a/.github/etc/dictionary.txt b/.github/etc/dictionary.txt index ac9b72d..577a36a 100644 --- a/.github/etc/dictionary.txt +++ b/.github/etc/dictionary.txt @@ -1,7 +1,14 @@ allstar +anchore +buildx cookiecutter dependabot digestabot +dockerhub +envrc +htmlcov +pylance +pythonpath refurb skopeo syft diff --git a/CLAUDE.md b/CLAUDE.md index f618381..b3e1adc 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -55,13 +55,10 @@ This is a **template generator** that creates Python projects with: task init # Run tests and linting -task build test +task lint build test # Generate a project from template -uvx cookiecutter . - -# Test template with default values -pytest tests/ +uvx --with gitpython cookiecutter . ``` ## When Making Changes @@ -71,6 +68,7 @@ pytest tests/ 3. **Test Thoroughly**: Both template and generated projects 4. **Document Changes**: Update relevant documentation 5. **Security First**: No hardcoded secrets, follow OWASP guidelines +6. **Maintain Documentation**: When making changes to features, update the corresponding documentation in the `docs/` folder ## Template Variables @@ -134,6 +132,10 @@ def test_template_generation(cookies): 4. Keep dependencies updated 5. Follow principle of least privilege +## Documentation Structure + +The project documentation is organized in the `docs/` folder. When modifying any feature documented above, ensure the corresponding documentation is updated. + ## Helpful Context - The template is designed for "vibe coding" - AI assistants should understand patterns without verbose prompts diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 240ef40..d67ad4c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,7 +2,7 @@ To contribute to this project, please fork the repository and open a pull request with your changes. -Also, see our Contributors Code of Conduct [here](./.github/CONTRIBUTING.md). +Also, see our Contributors Code of Conduct [here](./.github/CODE_OF_CONDUCT.md). ## Updating the dependencies diff --git a/README.md b/README.md index 5f380d3..31bbafb 100644 --- a/README.md +++ b/README.md @@ -19,7 +19,7 @@ Make your tools meet every requirement on the first pass, letting you ship faste - 📦 Ensure usability across all major platforms with multi-platform Docker builds - 🔄 Automated versioning and releasing with `python-semantic-release` -For FAQs including release workflow troubleshooting, see our [FAQ documentation](./FAQ.md) +For more details, see our [documentation](docs/index.md). ## Getting Started @@ -61,13 +61,3 @@ git checkout -b initial-content # Check for `NotImplementedError`s and address them as a part of adding your business logic grep -r NotImplementedError * ``` - -### Optional setup - -If you'd like to support license file checking locally, you will need to install `grant` and put it in your `PATH` - -Additionally, if you'd like to use SSH instead of HTTPS to connect to the `ai-native-python` project, use this command instead: - -```bash -uvx --with gitpython cookiecutter git+ssh://git@github.com/zenable-io/ai-native-python.git -``` diff --git a/docs/ai-ide-support.md b/docs/ai-ide-support.md new file mode 100644 index 0000000..1daa9c0 --- /dev/null +++ b/docs/ai-ide-support.md @@ -0,0 +1,43 @@ +# AI IDE Support + +The AI-Native Python template includes configuration files to work seamlessly with AI-powered development tools. + +## Tool-agnostic configurations + +### .mcp.json + +Model Context Protocol configuration pre-set to integrate with: + +- [Zenable](https://zenable.io)'s MCP server +- [Context7](https://context7.com/)'s MCP server + +## Specific IDE configurations + +### Claude Code + +Every generated project includes a `CLAUDE.md` file with: + +- Project-specific context and guidelines +- Technology stack information +- Code style rules and patterns +- Common tasks and workflows + +### GitHub Copilot Configuration + +The template includes `.github/copilot-instructions.md` with: + +- Project-specific context for GitHub Copilot +- Code conventions and patterns +- Testing requirements and workflow +- Security considerations +- Common code patterns and examples +- Task automation commands + +### Cursor IDE Configuration + +The template includes `.cursor/rules/` directory with: + +- `project.mdc`: Always-active rules with project info, tech stack, and key commands +- `testing.mdc`: Auto-attached rules for test files with testing guidelines and patterns + +For more details on testing configuration and practices, see the [Testing Guide](testing.md). diff --git a/docs/ci-cd.md b/docs/ci-cd.md new file mode 100644 index 0000000..55abb6d --- /dev/null +++ b/docs/ci-cd.md @@ -0,0 +1,50 @@ +# CI/CD Workflows + +The AI-Native Python template includes GitHub Actions workflows for automated testing, security scanning, and release management. + +## Included Workflows + +### CI Pipeline (`.github/workflows/ci.yml`) + +Runs on every push and pull request: + +1. **Linting** - Python (Ruff), YAML/JSON, shell scripts, GitHub Actions +2. **Testing** - Unit and integration tests with >80% coverage requirement +3. **Security** - Vulnerability scanning (Grype), SBOM generation (Syft), secret detection +4. **Docker** - Optional multi-platform builds with security scanning + +### Release Pipeline (`.github/workflows/release.yml`) + +Automates semantic versioning and publishing: + +1. Analyzes commit messages to determine version bump +2. Updates version in `pyproject.toml` +3. Generates changelog +4. Creates GitHub release +5. Pushes Docker images (if enabled) + +### PR Validation (`.github/workflows/pr.yml`) + +Ensures pull request quality: +- Validates PR title follows conventional commit format +- Checks all commit messages +- Enforces branch protection rules + +## Configuration + +For GitHub Actions configuration and required secrets, see the [Configuration Guide](configuration.md#post-generation-configuration). + +For Docker Hub setup specifically, if enabled during project generation, you'll need to set: +- `DOCKERHUB_USERNAME` +- `DOCKERHUB_PAT` + +### Dependency Updates + +The generated project includes multiple dependency update mechanisms. See the [Configuration Guide](configuration.md#post-generation-configuration) for details +on customizing these tools. + +## Customization + +### Custom Workflows + +Add new workflows in `.github/workflows/` for specific needs like deployment or scheduled tasks. diff --git a/docs/configuration.md b/docs/configuration.md new file mode 100644 index 0000000..698aaea --- /dev/null +++ b/docs/configuration.md @@ -0,0 +1,82 @@ +# Configuration Guide + +This guide covers the configuration options available in the AI-Native Python cookiecutter template. + +## Cookiecutter Variables + +When generating a new project, you'll be prompted for the following configuration options: + +### Basic Project Information + +| Variable | Description | Default | Example | +| --------------------------- | -------------------------------- | -------------- | --------------------------- | +| `project_name` | Human-readable project name | (required) | "My Awesome Project" | +| `project_slug` | Python package name (snake_case) | Auto-generated | "my_awesome_project" | +| `project_short_description` | Brief project description | (required) | "A tool for awesome things" | + +### Organization Details + +| Variable | Description | Default | Example | +| ------------------------------- | ------------------------------- | ---------- | ----------- | +| `company_name` | Your organization's name | (required) | "Acme Corp" | +| `company_domain` | Your organization's domain | (required) | "acme.com" | +| `github_org` | GitHub organization or username | (required) | "acme-corp" | +| `project_owner_github_username` | Project owner's GitHub username | (required) | "johndoe" | + +### Technical Options + +| Variable | Description | Default | Options | +| ---------------- | ---------------------------- | ------- | ----------------------------- | +| `python_version` | Minimum Python version | "3.13" | "3.11", "3.12", "3.13" | +| `dockerhub` | Enable Docker Hub publishing | "no" | "yes", "no" | +| `public` | Make repository public | "yes" | "yes", "no" | +| `license` | Project license | "NONE" | "NONE", "MIT", "BSD-3-Clause" | + +## Post-Generation Configuration + +After your project is generated, you are able to make any changes you'd like. Here are some common modifications: + +### Environment Variables + +Create or modify the `.envrc` file in your project root: + +```bash +# API Keys +export ZENABLE_API_KEY="your-api-key-here" + +# Development settings +export PYTHONPATH="${PWD}/src:${PYTHONPATH}" +export UV_PYTHON_PREFERENCE="only-system" +``` + +### Task Configuration + +The `Taskfile.yml` in your project defines common development tasks. You can customize anything you'd like, such as: + +- Python versions +- Linting and cleanup tasks +- Build configurations + +Example task customization: + +```yaml +vars: + IMAGE_NAME: "abc123" # Change the name of the docker image + PYTHON_VERSION: "3.13" # Change default Python version +``` + +### Pre-commit Hooks + +For detailed information about pre-commit hooks configuration and available hooks, see the [Hooks Guide](hooks.md#pre-commit-hooks). + +### GitHub Actions Configuration + +For detailed information about CI/CD workflows and customization options, see the [CI/CD Guide](ci-cd.md). + +#### Required Secrets + +If you enabled Docker Hub publishing: +- `DOCKERHUB_USERNAME` +- `DOCKERHUB_PAT` + +These will be printed as a reminder after project generation. diff --git a/FAQ.md b/docs/faq.md similarity index 83% rename from FAQ.md rename to docs/faq.md index ba087f7..8b4a0a8 100644 --- a/FAQ.md +++ b/docs/faq.md @@ -10,7 +10,8 @@ ### Q: Why is my release workflow failing with permission errors? -**A:** The release workflow requires the GitHub Actions bot to have permission to push commits to the main branch. This is necessary because semantic-release creates a commit to update version numbers in files. +**A:** The release workflow requires the GitHub Actions bot to have permission to push commits to the main branch. This is necessary because semantic-release +creates a commit to update version numbers in files. #### Solution: @@ -36,16 +37,6 @@ If you've already generated the project and just want to fix it up from here, fo - The organization may need to explicitly grant the GitHub Actions app permission to push - Contact your organization administrators if default permissions are restricted -### Q: Why does semantic-release fail with "no commits to release"? - -**A:** Semantic-release uses conventional commits to determine the next version. If there are no commits following the conventional commit format since the last release, it won't create a new release. - -Ensure your commits follow the format: -- `feat:` for new features (triggers minor version bump) -- `fix:` for bug fixes (triggers patch version bump) -- `BREAKING CHANGE:` in the commit body (triggers major version bump) -- Other types like `docs:`, `chore:`, `style:` don't trigger releases - ### Q: Can I manually specify the version number? **A:** No, the workflow is designed to automatically determine the version based on conventional commits. This ensures consistent versioning across all diff --git a/docs/hooks.md b/docs/hooks.md new file mode 100644 index 0000000..f65600b --- /dev/null +++ b/docs/hooks.md @@ -0,0 +1,73 @@ +# Hooks + +The AI-Native Python template uses hooks to automate setup tasks automatically. + +## Cookiecutter Hooks + +### Post-Generation Hook + +The `post_gen_project.py` hook runs after project generation to: + +1. Initialize the project as a Git repository +2. Create the project's initial commit +3. Set up GitHub remote (if credentials available) +4. Generate a fully up-to-date `uv.lock` file +5. Create an `.envrc` with API keys +6. Run `task init` to install dependencies +7. Push to GitHub and create an initial release + +### Configuration + +Environment variables can be set before running cookiecutter to modify hook behavior: + +- `SKIP_GIT_PUSH=true` - Skip automatic Git push +- `RUN_POST_HOOK=false` - Skip the post-generation hook entirely (not recommended) +- `ZENABLE_API_KEY="..."` - Auto-populate API key in .envrc + +For more environment variable options, see the [Optional Setup Guide](optional-setup.md#environment-variable-configuration). + +## Pre-commit Hooks + +Automatically run code quality checks before each commit. + +### Installation + +```bash +task init # Installs pre-commit and sets up hooks, alongside setting up other project dependencies to get started +``` + +### Included Hooks + +1. **Python** - Ruff for linting and formatting +2. **Security** - Trufflehog for secret detection +3. **File Checks** - JSON/YAML validation, large files, merge conflicts +4. **Spell Check** - Typos with custom dictionary +5. **Shell Scripts** - ShellCheck validation +6. **GitHub Actions** - Actionlint validation +7. **OpenAPI** - Schema validation + +For the full list of hooks, see `{{cookiecutter.project_name|replace(" ", "")}}/.pre-commit-config.yaml` + +### Configuration + +Edit `.pre-commit-config.yaml` to customize: + +```yaml +- repo: https://github.com/astral-sh/ruff-pre-commit + rev: v0.8.6 + hooks: + - id: ruff + args: [--fix, --show-fixes] +``` + +### Adding Custom Hooks + +```yaml +- repo: local + hooks: + - id: pytest-check + name: pytest-check + entry: pytest + language: system + pass_filenames: false +``` diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..b3f6757 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,33 @@ +# AI-Native Python Documentation + +Welcome to the AI-Native Python documentation. This guide will help you understand and use the AI-Native Python cookiecutter template effectively. + +## Documentation Structure + +### Getting Started +- [Configuration Guide](configuration.md) - Cookiecutter variables and post-generation setup +- [Optional Setup](optional-setup.md) - Additional tools and configurations + +### Development Workflow +- [AI IDE Support](ai-ide-support.md) - Claude, Copilot, and Cursor configurations +- [Testing](testing.md) - Test structure, running tests, and coverage +- [Hooks](hooks.md) - Cookiecutter and pre-commit hooks + +### Automation & Deployment +- [CI/CD Workflows](ci-cd.md) - GitHub Actions pipelines and automation +- [FAQ](faq.md) - Common issues and solutions + +### Future Development +- [Roadmap](roadmap.md) - Planned features and improvements + +## Quick Links + +- [Main README](../README.md) +- [Contributing Guidelines](../CONTRIBUTING.md) +- [GitHub Repository](https://github.com/zenable-io/ai-native-python) + +## Need Help? + +If you encounter issues not covered in these docs: +1. Check the [FAQ](faq.md) +2. [Open an issue](https://github.com/zenable-io/ai-native-python/issues/new) diff --git a/docs/optional-setup.md b/docs/optional-setup.md new file mode 100644 index 0000000..7c1198f --- /dev/null +++ b/docs/optional-setup.md @@ -0,0 +1,53 @@ +# Optional Setup Guide + +This guide covers optional setup steps and configurations for the AI-Native Python template. + +## Grant Installation (License Compliance) + +If you'd like to support license file checking locally, you will need to install `grant` and put it in your `PATH`. See [their installation +guide](https://github.com/anchore/grant?tab=readme-ov-file#installation) for more details + +## SSH Configuration for Cookiecutter + +If you prefer to use SSH instead of HTTPS for cloning the template, you can use the SSH URL. + +### Prerequisites + +1. SSH key configured with GitHub: + + ```bash + # Check for existing SSH keys + ls -la ~/.ssh + + # Generate new SSH key if needed + ssh-keygen -t ed25519 -C "your_email@example.com" + ``` + +2. Add SSH key to GitHub: + + ```bash + # Copy public key + cat ~/.ssh/id_ed25519.pub + # Add to GitHub: Settings -> SSH and GPG keys + ``` + +3. Test SSH connection: + + ```bash + ssh -T git@github.com + ``` + +### Using SSH with Cookiecutter + +```bash +# Use SSH URL instead of HTTPS +uvx --with gitpython cookiecutter git+ssh://git@github.com/zenable-io/ai-native-python.git +``` + +## Environment Variable Configuration + +Generated projects include an `.envrc` file for environment-specific settings. API keys can be pre-populated during project generation by setting environment +variables before running cookiecutter (see the [Hooks Guide](hooks.md#configuration)). + +To request support for additional API keys, please [open an issue](https://github.com/Zenable-io/ai-native-python/issues/new) or [pull +request](../CONTRIBUTING.md)! diff --git a/ROADMAP.md b/docs/roadmap.md similarity index 90% rename from ROADMAP.md rename to docs/roadmap.md index bcda404..838aeb3 100644 --- a/ROADMAP.md +++ b/docs/roadmap.md @@ -15,6 +15,7 @@ This document outlines future improvements and enhancements for the ai-native-py - Keep the public yes/no but split out a CodeQL yes/no (default to yes; secure by default but it may error if insufficient licensing) - Improve the docs around releasing and rulesets/branch protections +- Add support for releasing to pypi via oidc ### 3. Improve project health checks @@ -65,10 +66,4 @@ We welcome community feedback and contributions. Some areas where we'd especiall ## Contributing -If you're interested in contributing to any of these roadmap items, please: - -1. Open an issue to discuss the feature -2. Submit a pull request with your implementation -3. Update this roadmap as items are completed - -For more information, see [CONTRIBUTING.md](.github/CONTRIBUTING.md) +If you're interested in contributing to any of these roadmap items, please see our [contribution guide](../CONTRIBUTING.md), and thank you! 🎉 diff --git a/docs/testing.md b/docs/testing.md new file mode 100644 index 0000000..93e99cc --- /dev/null +++ b/docs/testing.md @@ -0,0 +1,61 @@ +# Testing Guide + +This document covers two distinct testing contexts: + +1. **Template Tests** - Tests for the AI-Native Python cookiecutter template itself (i.e. this repository) +2. **Generated Project Tests** - Tests included in projects created from this template (i.e. projects rendered after running `cookiecutter`) + +## Template Tests + +These tests ensure the cookiecutter template works correctly and generates valid projects. + +### Running Template Tests + +```bash +# From this repository +task test # Run all template tests with coverage +task unit-test # Run unit tests only +task integration-test # Run integration tests only +``` + +### What Template Tests Cover + +- **Generation Validation**: Tests with various input combinations to ensure valid project generation +- **Hook Execution**: Verifies post-generation hooks run correctly +- **File Structure**: Confirms all expected files are created +- **End-to-End**: Full test of the default parameter answers including: + - Project initialization + - Dependency installation + - Running generated project's test suite and linters + +## Generated Project Tests + +Every project created from this template includes a complete testing setup. + +### Features Included + +- **100% Coverage**: Template provides tests for the initial `main.py` and module code +- **Pytest Configuration**: Pre-configured in `pyproject.toml` +- **Coverage Requirements**: 80% minimum enforced in CI/CD + +### Running Tests in Generated Projects + +```bash +# From the generated project root +task test # Run all tests with coverage +pytest tests/unit -v # Run unit tests only +pytest tests/integration -v # Run integration tests only +``` + +### Writing Tests in Generated Projects + +Generated projects use pytest with: + +- Parametrized tests for multiple scenarios +- Markers for test categorization (`@pytest.mark.unit`, `@pytest.mark.integration`) +- Mocking for external dependencies + +## CI/CD Integration + +The above tests are a part of what's automatically executed in the CI pipeline. For complete details on test automation and workflow configuration, see the +[CI/CD Guide](ci-cd.md#ci-pipeline-githubworkflowsciyml). From b5ce5197d22153f50355c8ad68c9263415f409fd Mon Sep 17 00:00:00 2001 From: Jon Zeolla Date: Wed, 16 Jul 2025 13:02:16 -0400 Subject: [PATCH 2/4] More --- .cursor/rules/python-template.mdc | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/.cursor/rules/python-template.mdc b/.cursor/rules/python-template.mdc index 04a7d69..9d70e92 100644 --- a/.cursor/rules/python-template.mdc +++ b/.cursor/rules/python-template.mdc @@ -41,6 +41,7 @@ task lint # Check code quality ## Template Testing ```bash -uvx --with gitpython cookiecutter . # Generate project -pytest tests/ # Test template +uvx --with gitpython cookiecutter . --no-input # Generate a default project +cd $(ls -td * | head -1) +task init test # Test the template ``` From c213d07749bc374c3ff14ad6da0bb72e57f751e5 Mon Sep 17 00:00:00 2001 From: Jon Zeolla Date: Wed, 16 Jul 2025 13:09:41 -0400 Subject: [PATCH 3/4] Tweask --- CONTRIBUTING.md | 5 +++-- docs/ci-cd.md | 14 ++++---------- docs/configuration.md | 9 +++------ 3 files changed, 10 insertions(+), 18 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d67ad4c..dcfce46 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,8 +1,9 @@ # Contributing -To contribute to this project, please fork the repository and open a pull request with your changes. +To contribute to this project, please consider starting by [opening an issue](https://github.com/Zenable-io/ai-native-python/issues/new) to discuss the feature +and its design, and reviewing our Contributors Code of Conduct [here](./.github/CODE_OF_CONDUCT.md). -Also, see our Contributors Code of Conduct [here](./.github/CODE_OF_CONDUCT.md). +Once you are ready to submit your contribution, please fork the repository and open a pull request with your changes. ## Updating the dependencies diff --git a/docs/ci-cd.md b/docs/ci-cd.md index 55abb6d..3865169 100644 --- a/docs/ci-cd.md +++ b/docs/ci-cd.md @@ -9,9 +9,8 @@ The AI-Native Python template includes GitHub Actions workflows for automated te Runs on every push and pull request: 1. **Linting** - Python (Ruff), YAML/JSON, shell scripts, GitHub Actions -2. **Testing** - Unit and integration tests with >80% coverage requirement +2. **Testing** - Unit and integration tests with >80% coverage requirement, as well as docker builds on each supported platform 3. **Security** - Vulnerability scanning (Grype), SBOM generation (Syft), secret detection -4. **Docker** - Optional multi-platform builds with security scanning ### Release Pipeline (`.github/workflows/release.yml`) @@ -21,23 +20,20 @@ Automates semantic versioning and publishing: 2. Updates version in `pyproject.toml` 3. Generates changelog 4. Creates GitHub release -5. Pushes Docker images (if enabled) +5. Pushes Docker images to Docker Hub (if enabled) ### PR Validation (`.github/workflows/pr.yml`) Ensures pull request quality: + - Validates PR title follows conventional commit format - Checks all commit messages -- Enforces branch protection rules +- Look for deprecations or warnings and adds them to the finalizer ## Configuration For GitHub Actions configuration and required secrets, see the [Configuration Guide](configuration.md#post-generation-configuration). -For Docker Hub setup specifically, if enabled during project generation, you'll need to set: -- `DOCKERHUB_USERNAME` -- `DOCKERHUB_PAT` - ### Dependency Updates The generated project includes multiple dependency update mechanisms. See the [Configuration Guide](configuration.md#post-generation-configuration) for details @@ -45,6 +41,4 @@ on customizing these tools. ## Customization -### Custom Workflows - Add new workflows in `.github/workflows/` for specific needs like deployment or scheduled tasks. diff --git a/docs/configuration.md b/docs/configuration.md index 698aaea..11f56c7 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -69,14 +69,11 @@ vars: For detailed information about pre-commit hooks configuration and available hooks, see the [Hooks Guide](hooks.md#pre-commit-hooks). -### GitHub Actions Configuration - -For detailed information about CI/CD workflows and customization options, see the [CI/CD Guide](ci-cd.md). - -#### Required Secrets +#### Docker Hub Secrets If you enabled Docker Hub publishing: + - `DOCKERHUB_USERNAME` - `DOCKERHUB_PAT` -These will be printed as a reminder after project generation. +A reminder to set this is also printed after project generation if you answered "yes" to the docker hub question. From b1dd773596b5b4285d8473020c3325149fae8eb8 Mon Sep 17 00:00:00 2001 From: Jon Zeolla Date: Wed, 16 Jul 2025 13:13:28 -0400 Subject: [PATCH 4/4] Tweaks --- docs/ai-ide-support.md | 3 +++ docs/ci-cd.md | 2 ++ docs/configuration.md | 2 ++ docs/faq.md | 2 ++ docs/hooks.md | 2 ++ docs/index.md | 2 +- docs/optional-setup.md | 2 ++ docs/roadmap.md | 2 ++ docs/testing.md | 8 +++++--- 9 files changed, 21 insertions(+), 4 deletions(-) diff --git a/docs/ai-ide-support.md b/docs/ai-ide-support.md index 1daa9c0..ee59b65 100644 --- a/docs/ai-ide-support.md +++ b/docs/ai-ide-support.md @@ -2,6 +2,9 @@ The AI-Native Python template includes configuration files to work seamlessly with AI-powered development tools. +[← Back to Documentation Index](index.md) + + ## Tool-agnostic configurations ### .mcp.json diff --git a/docs/ci-cd.md b/docs/ci-cd.md index 3865169..61b6c56 100644 --- a/docs/ci-cd.md +++ b/docs/ci-cd.md @@ -2,6 +2,8 @@ The AI-Native Python template includes GitHub Actions workflows for automated testing, security scanning, and release management. +[← Back to Documentation Index](index.md) + ## Included Workflows ### CI Pipeline (`.github/workflows/ci.yml`) diff --git a/docs/configuration.md b/docs/configuration.md index 11f56c7..3c984c6 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -2,6 +2,8 @@ This guide covers the configuration options available in the AI-Native Python cookiecutter template. +[← Back to Documentation Index](index.md) + ## Cookiecutter Variables When generating a new project, you'll be prompted for the following configuration options: diff --git a/docs/faq.md b/docs/faq.md index 8b4a0a8..f292002 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -1,5 +1,7 @@ # Frequently Asked Questions +[← Back to Documentation Index](index.md) + ## Version Control System support ### Q: Do you support version control platforms other than GitHub? diff --git a/docs/hooks.md b/docs/hooks.md index f65600b..60f17a4 100644 --- a/docs/hooks.md +++ b/docs/hooks.md @@ -2,6 +2,8 @@ The AI-Native Python template uses hooks to automate setup tasks automatically. +[← Back to Documentation Index](index.md) + ## Cookiecutter Hooks ### Post-Generation Hook diff --git a/docs/index.md b/docs/index.md index b3f6757..f912909 100644 --- a/docs/index.md +++ b/docs/index.md @@ -9,7 +9,7 @@ Welcome to the AI-Native Python documentation. This guide will help you understa - [Optional Setup](optional-setup.md) - Additional tools and configurations ### Development Workflow -- [AI IDE Support](ai-ide-support.md) - Claude, Copilot, and Cursor configurations +- [AI IDE Support](ai-ide-support.md) - such as configuring Claude, Copilot, Cursor, or other IDEs - [Testing](testing.md) - Test structure, running tests, and coverage - [Hooks](hooks.md) - Cookiecutter and pre-commit hooks diff --git a/docs/optional-setup.md b/docs/optional-setup.md index 7c1198f..90f8b3a 100644 --- a/docs/optional-setup.md +++ b/docs/optional-setup.md @@ -2,6 +2,8 @@ This guide covers optional setup steps and configurations for the AI-Native Python template. +[← Back to Documentation Index](index.md) + ## Grant Installation (License Compliance) If you'd like to support license file checking locally, you will need to install `grant` and put it in your `PATH`. See [their installation diff --git a/docs/roadmap.md b/docs/roadmap.md index 838aeb3..119aa24 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -2,6 +2,8 @@ This document outlines future improvements and enhancements for the ai-native-python project. +[← Back to Documentation Index](index.md) + ## Ideas ### 1. Add Policy as Code diff --git a/docs/testing.md b/docs/testing.md index 93e99cc..f6c496d 100644 --- a/docs/testing.md +++ b/docs/testing.md @@ -5,6 +5,8 @@ This document covers two distinct testing contexts: 1. **Template Tests** - Tests for the AI-Native Python cookiecutter template itself (i.e. this repository) 2. **Generated Project Tests** - Tests included in projects created from this template (i.e. projects rendered after running `cookiecutter`) +[← Back to Documentation Index](index.md) + ## Template Tests These tests ensure the cookiecutter template works correctly and generates valid projects. @@ -42,9 +44,9 @@ Every project created from this template includes a complete testing setup. ```bash # From the generated project root -task test # Run all tests with coverage -pytest tests/unit -v # Run unit tests only -pytest tests/integration -v # Run integration tests only +task test # Run all tests with coverage +task unit-test # Run unit tests only +task integration-test # Run integration tests only ``` ### Writing Tests in Generated Projects