From 629824bde9885e402c3d7ec5f3f3735b512ed2e8 Mon Sep 17 00:00:00 2001 From: Chisanan232 Date: Sat, 25 Apr 2026 10:38:06 +0800 Subject: [PATCH 1/8] =?UTF-8?q?=F0=9F=93=9D=20docs(AAASM-15):=20replace=20?= =?UTF-8?q?template=20README=20with=20Python=20SDK=20accurate=20guide?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 139 +++++++++++++++++++++++------------------------------- 1 file changed, 60 insertions(+), 79 deletions(-) diff --git a/README.md b/README.md index 907a9e2..65f4a44 100644 --- a/README.md +++ b/README.md @@ -1,115 +1,96 @@ # Agent Assembly Python SDK -## Overview +Python SDK for AI Agent Assembly, providing a simple client for connecting agents to a governance gateway. -The Agent Assembly Python SDK provides a governance-native runtime for AI agents. This SDK enables developers to integrate AI agent lifecycle management, policy enforcement, and audit logging into their applications. It follows a WebAssembly-like pattern with a Rust core runtime and Python client interface. +## Requirements +- Python `>=3.12,<4.0` -## Python versions support +## Installation -This library requires Python 3.12+ +From source: -[![Supported Versions](https://img.shields.io/pypi/pyversions/agent-assembly.svg?logo=python&logoColor=FBE072)](https://pypi.org/project/agent-assembly) - - -## Quickly Start - -```python -from agent_assembly import init_assembly +```bash +pip install git+https://github.com/AI-agent-assembly/python-sdk.git +``` -# Initialize the agent assembly -assembly = init_assembly( - gateway_url="https://gateway.agent-assembly.dev", - agent_id="my-agent-001" -) +For local development: -# Your agent is now ready with governance enabled +```bash +uv sync ``` -## Documentation - -🚧 The details of documentation ... +## Quick Start -## Reusable GitHub Actions Workflows & Actions +```python +import asyncio -This template provides a comprehensive set of **reusable GitHub Actions workflows and actions** that can be called from other repositories to standardize CI/CD operations. Projects using this template can leverage these centralized components for consistent automation. +from agent_assembly import init_assembly -### πŸš€ Key Features -- **Centralized Management**: All workflows and actions are maintained in this template repository -- **Standardized Operations**: Consistent CI/CD processes across all projects -- **Easy Integration**: Simple calls using external repository references -- **Comprehensive Coverage**: Testing, building, releasing, Docker operations, documentation, and setup utilities +async def main() -> None: + client = init_assembly( + gateway_url="http://localhost:8080", + agent_id="my-agent-001", + api_key="optional-api-key", + ) -### πŸ“‹ Available Workflows + try: + registration = await client.register_agent() + decision = await client.check_policy_compliance("tool.call") + print(registration) + print(decision) + finally: + client.close() -| Workflow | Purpose | Key Features | -|------------------------------------------------------|------------------------------|----------------------------------------| -| `rw_build_and_test.yaml` | Run comprehensive test suite | Unit, integration, e2e, contract tests | -| `rw_run_all_test_and_record.yaml` | Complete CI with reporting | CodeCov upload, SonarCloud analysis | -| `rw_python_package.yaml` | Python package operations | Build, test, publish to PyPI | -| `rw_docker_operations.yaml` | Docker operations | Build, test, push, security scanning | -| `rw_parse_release_intent.yaml` | Release configuration parser | Determines release components | -| `rw_build_git-tag_and_create_github-release_v2.yaml` | Git tagging and releases | Automated version management | -| `rw_docs_operations.yaml` | Documentation operations | Build, version, deploy docs | -### πŸ“¦ Available Actions +asyncio.run(main()) +``` -| Action | Purpose | Key Features | -|--------|---------|--------------| -| `setup-python-uv` | Python & UV setup with dependencies | Multi-version support, intelligent caching, flexible dependency groups | +## Public API -### πŸ”§ Quick Start +- `init_assembly(gateway_url, agent_id, api_key=None) -> GatewayClient` +- `GatewayClient.register_agent() -> dict` +- `GatewayClient.check_policy_compliance(action: str) -> dict` +- Exceptions: `AssemblyError`, `AgentError`, `PolicyError`, `GatewayError`, `ConfigurationError` +- Data models: `AgentConfig`, `AgentState`, `PolicyEvaluation` -To use these reusable workflows in your project, simply call them using external repository references: +## Error Handling -```yaml -# .github/workflows/ci.yaml in your project -name: CI -on: - push: - branches: [main] - pull_request: - branches: [main] +```python +from agent_assembly import init_assembly +from agent_assembly.exceptions import ConfigurationError -jobs: - test: - uses: Chisanan232/Template-Python-UV-Project/.github/workflows/rw_run_all_test_and_record.yaml@master - secrets: - codecov_token: ${{ secrets.CODECOV_TOKEN }} - sonar_token: ${{ secrets.SONAR_TOKEN }} +try: + client = init_assembly(gateway_url="", agent_id="my-agent-001") +except ConfigurationError as exc: + print(f"Invalid configuration: {exc}") ``` -### πŸ“š Complete Documentation - -- **[Reusable Workflows Guide](.github/workflows/REUSABLE_WORKFLOWS.md)**: Complete documentation with all inputs, outputs, and usage examples -- **[Example Workflows](.github/workflows/examples/)**: Ready-to-use example workflows for common scenarios -- **Template Placeholders**: All workflows use `` placeholders for easy customization - -### πŸ’‘ Benefits for Projects Using This Template - -1. **Reduced Boilerplate**: No need to write complex CI/CD workflows from scratch -2. **Best Practices**: Workflows follow established patterns and security practices -3. **Automatic Updates**: Bug fixes and improvements are centrally maintained -4. **Consistency**: Same workflow behavior across all projects using the template -5. **Easy Maintenance**: Update workflows in one place, benefits all projects +## Development +Run tests: -## Coding style and following rules - -**__** follows coding styles **_black_** and **_PyLint_** to control code quality. +```bash +uv run pytest +``` -[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black) -[![linting: pylint](https://img.shields.io/badge/linting-pylint-yellowgreen)](https://github.com/pylint-dev/pylint) +Run integration tests: +```bash +uv run pytest -m integration +``` -## Downloading state +Lint and type-check: -🚧 The download state for your library +```bash +uv run ruff check . +uv run mypy agent_assembly +``` -[![Downloads](https://pepy.tech/badge/)](https://pepy.tech/project/) -[![Downloads](https://pepy.tech/badge//month)](https://pepy.tech/project/) +## Documentation +- Project docs source: `docs/` ## License From 3d985101a38376113e38b07a3f1916c25b834843 Mon Sep 17 00:00:00 2001 From: Chisanan232 Date: Sat, 25 Apr 2026 20:47:48 +0800 Subject: [PATCH 2/8] =?UTF-8?q?=F0=9F=A7=B9=20docs:=20remove=20template=20?= =?UTF-8?q?blog=20section?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/README.md | 2 - .../blog/2025-09-01-project-origin.md | 105 ------------------ docs/contents/blog/authors.yml | 9 -- docs/contents/blog/tags.yml | 29 ----- docs/docusaurus.config.ts | 23 +--- 5 files changed, 1 insertion(+), 167 deletions(-) delete mode 100644 docs/contents/blog/2025-09-01-project-origin.md delete mode 100644 docs/contents/blog/authors.yml delete mode 100644 docs/contents/blog/tags.yml diff --git a/docs/README.md b/docs/README.md index 17b122e..5fa42ba 100644 --- a/docs/README.md +++ b/docs/README.md @@ -8,7 +8,6 @@ The documentation is organized into the following sections: - **πŸ“– Docs** - Main user documentation and guides - **πŸ‘¨β€πŸ’» Development** - Technical documentation for developers -- **✍️ Blog** - Project updates and technical articles ## πŸš€ Getting Started @@ -57,7 +56,6 @@ pnpm serve --no-open 1. Add new Markdown files to: - `contents/document/` for user documentation - `contents/development/` for developer documentation - - `contents/blog/` for blog posts 2. Update the appropriate sidebar configuration: - `contents/document/sidebars.ts` for docs diff --git a/docs/contents/blog/2025-09-01-project-origin.md b/docs/contents/blog/2025-09-01-project-origin.md deleted file mode 100644 index af154b1..0000000 --- a/docs/contents/blog/2025-09-01-project-origin.md +++ /dev/null @@ -1,105 +0,0 @@ ---- -slug: project-origin -title: Empowering Python Developers with a Modern Project Template -authors: [chisanan232] -tags: [python, uv, ci-cd, template, automation, developer-experience] ---- - -# Why I Created This Python UV Project Template - -As a Python developer, I've experienced the same frustration countless times: starting a new project and spending hours, sometimes days, setting up the same boilerplate code, CI/CD pipelines, testing frameworks, and deployment configurations. Each time, I found myself copy-pasting from previous projects, manually adjusting workflows, and inevitably missing some crucial setup step that would bite me later. - -This repetitive cycle was not just inefficientβ€”it was preventing me and other developers from focusing on what truly matters: **building great software and bringing ideas to life quickly**. - - - -## The Problem: Fragmented Development Setup - -The Python ecosystem, while rich and powerful, often requires developers to: - -- **Configure multiple tools separately**: UV for dependency management, pytest for testing, GitHub Actions for CI/CD, Docker for containerization -- **Set up complex CI/CD pipelines**: Multi-stage workflows, secret management, release automation -- **Handle deployment configurations**: PyPI publishing, Docker registry pushes, documentation deployment -- **Maintain consistency across projects**: Ensuring all projects follow the same patterns and best practices - -For experienced developers, this setup time is annoying. For newcomers to Python, it can be overwhelming and discouraging. - -## The Vision: Instant Project Readiness - -I envisioned a world where Python developers could: - -- **Start coding immediately**: Clone a template and have a fully functional project with CI/CD in minutes -- **Focus on their core idea**: Spend time on business logic, not infrastructure setup -- **Follow best practices automatically**: Get modern tooling, security features, and maintainable patterns by default -- **Scale effortlessly**: From prototype to production with centralized configuration management - -## Built with Modern Python Standards - -This template leverages the latest and greatest in the Python ecosystem: - -### **UV for Lightning-Fast Dependencies** -- **Faster installs**: Up to 100x faster than pip in many cases -- **Reproducible builds**: Lockfile-based dependency resolution -- **Modern standards**: Built-in support for PEP 621 and Python packaging best practices - -### **Centralized Configuration Management** -- **Single source of truth**: All project settings in `intent.yaml` -- **Smart defaults**: Works out of the box, customizable when needed -- **Environment-aware**: Different configurations for development, staging, and production - -### **Advanced CI/CD Architecture** -- **4-tier modular design**: From simple CI to complex release workflows -- **Dual authentication**: Modern OIDC and traditional token support for PyPI -- **Comprehensive testing**: Unit, integration, E2E, contract, and CI script tests -- **Multi-platform support**: Test across Python versions and operating systems - -## Real Impact: From Hours to Minutes - -### **Before This Template** -```bash -# Manual setup nightmare -mkdir my-project && cd my-project -# ... 2-4 hours of configuration ... -# Setting up pyproject.toml -# Configuring GitHub Actions -# Setting up testing framework -# Configuring PyPI publishing -# Setting up Docker -# Writing documentation config -# And inevitably forgetting something important -``` - -### **After This Template** -```bash -# Instant productivity -git clone https://github.com/Chisanan232/Template-Python-UV-Project.git my-project -cd my-project -# Edit intent.yaml with your project details -# Start coding your idea immediately! -``` - -## Project Goals: Developer Happiness Through Automation - -This template aims to provide: - -1. **πŸš€ Instant Setup**: From idea to deployed project in under 10 minutes -2. **πŸ”’ Security by Default**: Modern authentication, secret management, and security scanning -3. **πŸ“¦ Production-Ready**: Automated releases to PyPI, Docker registries, and documentation sites -4. **πŸ§ͺ Quality Assurance**: Comprehensive testing, coverage reporting, and code quality checks -5. **πŸ“š Self-Documenting**: Automated documentation generation and versioning -6. **πŸ”§ Highly Configurable**: Easy customization without losing the benefits of standardization -7. **🌐 Community-Driven**: Open source with comprehensive examples and best practices - -## The Journey Continues - -Since starting this project, it has evolved far beyond my initial vision. What began as a simple template has become a comprehensive platform for Python development, complete with: - -- **Centralized release management** with staging and validation workflows -- **Dual authentication systems** supporting both modern OIDC and traditional tokens -- **Modular CI architecture** that scales from simple projects to complex enterprise needs -- **Comprehensive documentation** with migration guides and troubleshooting -- **Real-world examples** covering every common use case - -This blog will continue to document the evolution of this template, sharing insights about modern Python development practices, CI/CD automation, and the pursuit of developer happiness through better tooling. - -**The goal remains simple: help Python developers spend more time building amazing things and less time fighting with infrastructure.** diff --git a/docs/contents/blog/authors.yml b/docs/contents/blog/authors.yml deleted file mode 100644 index 2e79207..0000000 --- a/docs/contents/blog/authors.yml +++ /dev/null @@ -1,9 +0,0 @@ -chisanan232: - name: Chisanan232 - title: This project Maintainer - url: https://github.com/Chisanan232 - image_url: https://github.com/Chisanan232.png - page: true - socials: - github: Chisanan232 - linkedin: bryant-liu-3a3aa3247 diff --git a/docs/contents/blog/tags.yml b/docs/contents/blog/tags.yml deleted file mode 100644 index 4af2d10..0000000 --- a/docs/contents/blog/tags.yml +++ /dev/null @@ -1,29 +0,0 @@ -python: - label: Python - permalink: /python - description: Python programming and development - -uv: - label: UV - permalink: /uv - description: UV package management and tooling - -ci-cd: - label: CI/CD - permalink: /ci-cd - description: Continuous Integration and Deployment workflows - -template: - label: Template - permalink: /template - description: Project template guidance and best practices - -automation: - label: Automation - permalink: /automation - description: Automation strategies for development workflows - -developer-experience: - label: Developer Experience - permalink: /developer-experience - description: Enhancements focused on developer productivity and experience diff --git a/docs/docusaurus.config.ts b/docs/docusaurus.config.ts index 97408a5..90982fc 100644 --- a/docs/docusaurus.config.ts +++ b/docs/docusaurus.config.ts @@ -103,17 +103,6 @@ const config: Config = { lastVersion: 'current', }, ], - [ - '@docusaurus/plugin-content-blog', - { - id: 'blog', - path: 'contents/blog', - routeBasePath: 'blog', - showReadingTime: true, - editUrl: - 'https://github.com/Chisanan232/Template-Python-UV-Project/tree/master/docs/', - }, - ], [ require.resolve('@easyops-cn/docusaurus-search-local'), { @@ -122,12 +111,11 @@ const config: Config = { language: ['en'], docsRouteBasePath: ['/uv-template'], docsDir: ['./contents/document', './contents/development'], - blogDir: ['./contents/blog'], highlightSearchTermsOnTargetPage: true, explicitSearchResultPath: true, docsPluginIdForPreferredVersion: 'docs', indexDocs: true, - indexBlog: true, + indexBlog: false, indexPages: true, }, ], @@ -161,11 +149,6 @@ const config: Config = { label: 'Dev', docsPluginId: 'dev', }, - { - to: '/blog', - label: 'Blog', - position: 'left', - }, { type: 'custom-unifiedVersions', position: 'right', @@ -202,10 +185,6 @@ const config: Config = { label: 'Dev', to: '/dev/next', }, - { - label: 'Blog', - to: '/blog', - }, ], }, { From 4d7ec7cc8686e58330a09bc9abe0f588eba297bd Mon Sep 17 00:00:00 2001 From: Chisanan232 Date: Sat, 25 Apr 2026 20:48:12 +0800 Subject: [PATCH 3/8] =?UTF-8?q?=F0=9F=A7=B9=20docs:=20remove=20template=20?= =?UTF-8?q?contribution=20pages?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/contents/document/contribute/discuss.mdx | 55 ------------ docs/contents/document/contribute/index.mdx | 43 --------- .../document/contribute/report-bug.mdx | 90 ------------------- .../document/contribute/request-changes.mdx | 88 ------------------ docs/contents/document/sidebars.ts | 26 ------ 5 files changed, 302 deletions(-) delete mode 100644 docs/contents/document/contribute/discuss.mdx delete mode 100644 docs/contents/document/contribute/index.mdx delete mode 100644 docs/contents/document/contribute/report-bug.mdx delete mode 100644 docs/contents/document/contribute/request-changes.mdx diff --git a/docs/contents/document/contribute/discuss.mdx b/docs/contents/document/contribute/discuss.mdx deleted file mode 100644 index f45856e..0000000 --- a/docs/contents/document/contribute/discuss.mdx +++ /dev/null @@ -1,55 +0,0 @@ ---- -id: discuss -title: Discuss Something -sidebar_position: 3 ---- - -# Discussing your repo - -Have questions, ideas, or want to connect with other users and developers? There are several ways to join the conversation around your repo. - -## Community Forums - -Our primary place for discussions is the [GitHub Discussions](https://github.com/Chisanan232/Template-Python-UV-Project/discussions) page. Here you can: - -- Ask questions about using the software -- Share your experiences and use cases -- Connect with other community members -- Discuss ideas before creating formal feature requests - -### Discussion Categories - -- **General**: General discussions about the project -- **Ideas**: Share ideas for improvements that aren't yet formal feature requests -- **Q&A**: Ask questions about using your repo -- **Show and Tell**: Share what you've built with your repo - -## Best Practices for Discussions - -1. **Search first**: Check if your topic has already been discussed before creating a new thread. -2. **Be clear**: Use descriptive titles and provide context in your posts. -3. **Be respectful**: Follow our [Code of Conduct](https://github.com/Chisanan232/Template-Python-UV-Project/blob/main/CODE_OF_CONDUCT.mdx). -4. **Use proper formatting**: Format code snippets, logs, and error messages using Markdown code blocks. -5. **Stay on topic**: Keep discussions focused on the original topic; create new threads for new topics. - -## Getting Help - -If you need help with a specific issue: - -1. **Documentation**: Start by checking our [documentation](/). -2. **Q&A**: Post your question in the Q&A category of our GitHub Discussions. -3. **Bug Reports**: If you've found a bug, follow the [bug reporting guidelines](./report-bug.mdx). - -## Developer Discussions - -For discussions specifically about development, contributing code, or technical details: - -1. **Development Guide**: Start with our [Development Guide](/dev/next). -2. **Pull Requests**: Comment on relevant [Pull Requests](https://github.com/Chisanan232/Template-Python-UV-Project/pulls) for implementation discussions. -3. **Technical Discussions**: Use the GitHub Discussions "Development" category for broader technical topics. - -## Community Guidelines - -All community interactions should follow our [Code of Conduct](https://github.com/Chisanan232/Template-Python-UV-Project/blob/main/CODE_OF_CONDUCT.mdx). We aim to foster an inclusive, welcoming, and productive environment for all contributors and users. - -Join our community today and help shape the future of your repo! diff --git a/docs/contents/document/contribute/index.mdx b/docs/contents/document/contribute/index.mdx deleted file mode 100644 index 578efd7..0000000 --- a/docs/contents/document/contribute/index.mdx +++ /dev/null @@ -1,43 +0,0 @@ ---- -id: contribute -title: Welcome to Contribute -sidebar_position: 4 ---- - -# Welcome to Contribute - -Thank you for your interest in contributing to your repo! We welcome contributions from everyone, whether you're fixing a typo or implementing a new feature. - -## Ways to Contribute - -There are many ways you can help improve your repo: - -### Report a Bug - -If you've found a bug in the application, please [report it](./report-bug.mdx) using our bug report template. Be sure to include: - -- A clear description of the issue -- Steps to reproduce the problem -- Expected vs. actual behavior -- Version information -- Any relevant logs or screenshots - -### Request Additions or Changes - -Have an idea for a new feature or improvement? We'd love to hear it! Check out our [feature request guidelines](./request-changes.mdx) to learn how to submit your ideas effectively. - -### Discuss Something - -Have questions or want to discuss aspects of the project? Join the conversation in our [discussion forum](./discuss.mdx) or start a new thread. - -## Development Guide - -If you're interested in contributing code to the project, please refer to our [Development Guide](/dev/next/) for detailed information on: - -- Setting up your development environment -- Understanding the project architecture -- Following coding standards and conventions -- Testing your changes -- Submitting pull requests - -We look forward to your contributions! diff --git a/docs/contents/document/contribute/report-bug.mdx b/docs/contents/document/contribute/report-bug.mdx deleted file mode 100644 index 7664105..0000000 --- a/docs/contents/document/contribute/report-bug.mdx +++ /dev/null @@ -1,90 +0,0 @@ ---- -id: report-bug -title: Report a Bug -sidebar_position: 1 ---- - -# Reporting Bugs - -We appreciate your help in identifying and reporting bugs in your repo. A well-documented bug report helps us understand and fix issues quickly. - -## Before Reporting - -Before submitting a bug report, please: - -1. **Check existing issues**: Search the [GitHub Issues](https://github.com/Chisanan232/Template-Python-UV-Project/issues) to see if the bug has already been reported. -2. **Update to the latest version**: Verify that you're using the latest version of the software, as the bug may have been fixed already. -3. **Confirm it's a bug**: Make sure the behavior you're experiencing is truly a bug and not expected behavior or a configuration issue. - -## How to Submit a Bug Report - -Please submit bug reports through our [GitHub Issues](https://github.com/Chisanan232/Template-Python-UV-Project/issues) page using the "Bug Report" template. - -### What to Include - -An effective bug report should include: - -1. **Clear and descriptive title**: Summarize the issue concisely. -2. **Environment details**: - - Operating system and version - - Python version - - your repo version - - Installation method (pip, source, Docker) - - Any relevant configuration - -3. **Steps to reproduce**: - - Be specific and provide a step-by-step guide to reproduce the issue - - Include example code if applicable - - Mention any specific conditions or setup required - -4. **Expected behavior**: Describe what you expected to happen. - -5. **Actual behavior**: Describe what actually happened. - -6. **Error messages**: Include any error messages or logs (use code blocks for formatting). - -7. **Screenshots or recordings**: If applicable, include visual evidence of the issue. - -8. **Possible solution**: If you have insights into what might be causing the issue or ideas for fixing it, please share them. - -## Example Bug Report - -``` -Title: Server crashes when handling concurrent requests with SSE transport - -Environment: -- OS: Ubuntu 22.04 -- Python: 3.10.4 -- your repo: 0.2.1 -- Installed via pip - -Steps to Reproduce: -1. Start the server with SSE transport: `clickup-mcp-server --transport sse` -2. Create a test script that sends 10 concurrent requests -3. Execute the test script - -Expected Behavior: -All requests should be processed correctly, and responses returned to clients. - -Actual Behavior: -Server crashes with the following error: -``` -[ERROR] 2025-08-10 14:23:47 - Exception in SSE transport: RuntimeError: Cannot process concurrent requests -Traceback (most recent call last): - File "/usr/local/lib/python3.10/dist-packages/clickup_mcp_server/transport/sse.py", line 127, in handle_request - ... -``` - -Additional Information: -This only happens with SSE transport. HTTP streaming works fine with concurrent requests. -``` - -## After Submitting - -After you've submitted a bug report: - -- Be responsive to questions about the issue -- Provide additional information if requested -- Consider helping test the fix when it becomes available - -Thank you for helping improve your repo! diff --git a/docs/contents/document/contribute/request-changes.mdx b/docs/contents/document/contribute/request-changes.mdx deleted file mode 100644 index c7cc64a..0000000 --- a/docs/contents/document/contribute/request-changes.mdx +++ /dev/null @@ -1,88 +0,0 @@ ---- -id: request-changes -title: Request Additions or Changes -sidebar_position: 2 ---- - -# Requesting Additions or Changes - -Have an idea for improving your repo? We welcome feature requests and suggestions from our community! This guide will help you submit effective feature requests. - -## Before Submitting - -Before submitting a feature request, please: - -1. **Check existing requests**: Search the [GitHub Issues](https://github.com/Chisanan232/Template-Python-UV-Project/issues) to see if someone has already suggested a similar feature. -2. **Read the documentation**: Make sure the feature doesn't already exist or isn't already planned in our roadmap. -3. **Consider compatibility**: Think about how your suggestion fits with the existing architecture and goals of the project. - -## How to Submit a Feature Request - -Please submit feature requests through our [GitHub Issues](https://github.com/Chisanan232/Template-Python-UV-Project/issues) page using the "Feature Request" template. - -### What to Include - -An effective feature request should include: - -1. **Clear and descriptive title**: Summarize the proposed feature concisely. -2. **Problem statement**: Describe the problem that this feature would solve. - - What are you trying to accomplish? - - Why is it difficult or impossible with the current implementation? - - Who else might benefit from this feature? - -3. **Proposed solution**: Describe your idea for implementing the feature. - - Be as specific as possible - - Include mockups or diagrams if applicable - - Consider edge cases and potential issues - -4. **Alternative solutions**: Have you considered other ways to solve this problem? - -5. **Implementation considerations**: If you have technical insights about how to implement the feature, please share them. - -6. **Impact and importance**: Explain why this feature would be valuable to users and the project. - -## Example Feature Request - -``` -Title: Add WebSocket transport option for real-time updates - -Problem Statement: -Currently, your repo supports HTTP streaming and SSE for client communication. -However, for truly bidirectional real-time communication, these options have limitations. -Many modern web applications would benefit from WebSocket support for more efficient -real-time updates and lower latency. - -Proposed Solution: -Add a new transport option "websocket" that implements the WebSocket protocol. This would: -- Allow bidirectional communication between client and server -- Reduce overhead compared to HTTP polling or SSE -- Enable real-time updates for task changes, comments, etc. -- Follow the same MCP message format as existing transports - -The implementation should include: -1. New WebSocketTransport class implementing the Transport interface -2. Client-side connection handling and reconnection logic -3. Support for the same authentication mechanisms as existing transports - -Alternative Solutions: -1. Enhance the SSE implementation with custom headers for upstream communication -2. Implement long-polling with improved efficiency - -Implementation Considerations: -This would require adding a WebSocket library dependency (e.g., websockets for Python). -Care should be taken to ensure proper connection management and resource cleanup. - -Impact and Importance: -This feature would greatly improve real-time applications built on your repo, -reducing latency and improving the user experience for collaborative tools. -``` - -## After Submitting - -After you've submitted a feature request: - -- Be responsive to questions about your proposal -- Be open to feedback and suggestions -- Consider contributing to the implementation if you have the skills - -Thank you for helping improve your repo! diff --git a/docs/contents/document/sidebars.ts b/docs/contents/document/sidebars.ts index d5dce0d..dd68233 100644 --- a/docs/contents/document/sidebars.ts +++ b/docs/contents/document/sidebars.ts @@ -90,32 +90,6 @@ const sidebars: SidebarsConfig = { // }, ], }, - { - type: 'category', - label: 'πŸ‘‹ Welcome to contribute', - items: [ - { - type: 'doc', - id: 'contribute/contribute', - label: '🀝 Contribute', - }, - { - type: 'doc', - id: 'contribute/report-bug', - label: 'πŸ› Report Bug', - }, - { - type: 'doc', - id: 'contribute/request-changes', - label: 'πŸ’‘ Request Changes', - }, - { - type: 'doc', - id: 'contribute/discuss', - label: 'πŸ’¬ Discuss', - }, - ], - }, { type: 'doc', id: 'changelog', From 600cc30e705e04ce19d73f08f3a1019d95044439 Mon Sep 17 00:00:00 2001 From: Chisanan232 Date: Sat, 25 Apr 2026 20:48:42 +0800 Subject: [PATCH 4/8] =?UTF-8?q?=F0=9F=A7=B9=20docs:=20remove=20template=20?= =?UTF-8?q?architecture=20and=20CI/CD=20pages?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/contents/development/architecture.mdx | 9 - .../development/architecture/index.mdx | 73 --- .../architecture/project-structure.mdx | 98 ---- .../ci-cd/additional-ci-workflows.mdx | 155 ----- .../ci-cd/continuous-integration.mdx | 384 ------------- .../development/ci-cd/developer-guide.mdx | 531 ------------------ .../ci-cd/documentation-deployment.mdx | 466 --------------- docs/contents/development/ci-cd/index.mdx | 96 ---- .../development/ci-cd/release-system.mdx | 130 ----- .../development/ci-cd/reusable-workflows.mdx | 27 - .../ci-cd/type-checking-workflow.mdx | 170 ------ docs/contents/development/sidebars.ts | 59 -- 12 files changed, 2198 deletions(-) delete mode 100644 docs/contents/development/architecture.mdx delete mode 100644 docs/contents/development/architecture/index.mdx delete mode 100644 docs/contents/development/architecture/project-structure.mdx delete mode 100644 docs/contents/development/ci-cd/additional-ci-workflows.mdx delete mode 100644 docs/contents/development/ci-cd/continuous-integration.mdx delete mode 100644 docs/contents/development/ci-cd/developer-guide.mdx delete mode 100644 docs/contents/development/ci-cd/documentation-deployment.mdx delete mode 100644 docs/contents/development/ci-cd/index.mdx delete mode 100644 docs/contents/development/ci-cd/release-system.mdx delete mode 100644 docs/contents/development/ci-cd/reusable-workflows.mdx delete mode 100644 docs/contents/development/ci-cd/type-checking-workflow.mdx diff --git a/docs/contents/development/architecture.mdx b/docs/contents/development/architecture.mdx deleted file mode 100644 index 1f0d4fb..0000000 --- a/docs/contents/development/architecture.mdx +++ /dev/null @@ -1,9 +0,0 @@ ---- -id: architecture -title: Software Architecture -sidebar_position: 5 ---- - -# Software Architecture - -This document provides an overview of the Python uv project template architecture, its core components, and how they interact with each other. diff --git a/docs/contents/development/architecture/index.mdx b/docs/contents/development/architecture/index.mdx deleted file mode 100644 index ca3d5b2..0000000 --- a/docs/contents/development/architecture/index.mdx +++ /dev/null @@ -1,73 +0,0 @@ ---- -id: architecture-overview -title: Architecture Overview -sidebar_position: 1 -slug: architecture/overview ---- - -# Template Architecture Overview - -This page explains how the Python UV Project Template is organized and how the main building blocks (source code, automation, and documentation) work together. Use it as a map when adapting the template to your own project. - -## Architecture Pillars - -- **Application Layer (`src/`)** – Houses your Python package using the modern src-layout. -- **Quality & Testing (`test/`, `pre-commit`)** – Provides pytest-based suites, coverage reporting, linting, and type-checking tooling configured through uv. -- **Automation (`.github/workflows/`)** – Collection of GitHub Actions for CI, releases, docs, Docker, and supporting tasks. -- **Documentation (`docs_with_docusarus/`, `docs_with_mkdocs/`)** – Docusaurus (primary) and MkDocs (optional) documentation systems ready for customization. - -## Repository Topology - -```mermaid -flowchart LR - subgraph Source - A[src/] - B[test/] - end - subgraph Automation - C[.github/workflows/] - D[scripts/] - end - subgraph Documentation - E[docs_with_docusarus/] - F[docs_with_mkdocs/] - end - subgraph Packaging - G[pyproject.toml] - H[uv.lock] - end - - A --> C - B --> C - C --> G - C --> H - A --> E - A --> F - E --> C -``` - -## What Lives Where? - -- **`src/`** – Your distributable package, including the default `types.py` example and `py.typed` marker for PEP 561 compliance. -- **`test/`** – Unit and integration test scaffolding with pytest plugins preconfigured in `pyproject.toml`. -- **`.github/workflows/`** – Automation entry points (CI, release, documentation, Docker, type distribution, etc.). -- **`docs_with_docusarus/`** – Primary documentation site (this guide). Includes reusable content, versioning, and search configuration. -- **`docs_with_mkdocs/`** – Alternate documentation stack if your team prefers MkDocs. -- **`scripts/`** – Helper scripts invoked by workflows for packaging, docs, and build orchestration. -- **`pyproject.toml` / `uv.lock`** – Single source of truth for dependencies, tool configuration, and packaging metadata. - -## How the Pieces Work Together - -1. **Develop locally with uv** – Use `uv sync` to install dependencies defined in `pyproject.toml` and locked in `uv.lock`. -2. **Validate with pre-commit** – Preconfigured hooks (formatting, linting, type checking) keep commits consistent. -3. **Run CI** – `ci.yaml` (regular) and `ci_includes_e2e_test.yaml` (extended) execute the same matrix of tests GitHub-side. -4. **Ship releases** – Intent-driven workflows publish Python packages, container images, and docs from a single configuration file. -5. **Publish docs** – Docusaurus builds run automatically after releases or documentation-only pull requests. - -## Related Guides - -- **Structure & Files** β†’ [Project Structure](./project-structure.mdx) -- **CI/CD System** β†’ [CI/CD Overview](../ci-cd/index.mdx) -- **Type Checking** β†’ [Type Checking with MyPy](../type-checking.mdx) - -Use these pages to drill into specific subsystems once you customize the template for your own project. diff --git a/docs/contents/development/architecture/project-structure.mdx b/docs/contents/development/architecture/project-structure.mdx deleted file mode 100644 index 3d32f7a..0000000 --- a/docs/contents/development/architecture/project-structure.mdx +++ /dev/null @@ -1,98 +0,0 @@ ---- -id: project-structure -title: Project Structure -sidebar_position: 2 ---- - -# Project Structure & Organization - -This page explains the default layout provided by the Python UV Project Template so you can quickly understand where to place code, configuration, and automation for your own project. - -## High-Level Layout - -``` -project/ -β”œβ”€β”€ src/ # Application/library source code -β”‚ └── your_package/ # Rename this to your real package name -β”‚ β”œβ”€β”€ __init__.py -β”‚ β”œβ”€β”€ types.py # Example for PEP 561 type distribution -β”‚ └── py.typed # Marker enabling downstream type checking -β”œβ”€β”€ test/ # Pytest-based test suites -β”‚ β”œβ”€β”€ unit_test/ -β”‚ └── integration_test/ -β”œβ”€β”€ docs_with_docusarus/ # Primary documentation (Docusaurus) -β”œβ”€β”€ docs_with_mkdocs/ # Optional MkDocs documentation -β”œβ”€β”€ scripts/ # Helper scripts used by workflows -β”œβ”€β”€ .github/workflows/ # GitHub Actions automation -β”œβ”€β”€ pyproject.toml # Project + tooling configuration -└── uv.lock # Locked dependency graph managed by uv -``` - -> **Tip:** Everything under `src/` is packaged and exported when you publish to PyPI. Everything else supports local development, automation, and documentation. - -## Source Code (`src/`) - -- Designed for the **src-layout** recommended by modern Python packaging. -- Ships with a minimal `types.py` + `py.typed` combo showing how to distribute type information. -- Rename the default package directory to match your project name and add modules as needed. -- Configure exports via `__init__.py` (or expose a public API) based on your needs. - -### Type Distribution Example - -The template demonstrates PEP 561 support out of the box: - -```python title="src/your_package/types.py" -type UserId = str -type Payload = dict[str, str | int | float | bool | None] - -__all__ = ["UserId", "Payload"] -``` - -Add additional aliases or Protocols here and keep `py.typed` in the same package so type checkers pick them up automatically. - -## Testing (`test/`) - -- Pytest folders split into `unit_test/` and `integration_test/` for clarity. -- Extend with more directories (e.g., `contract_test/`, `e2e_test/`) if your project requires broader coverage. -- Use the provided pytest plugins (coverage, asyncio, reruns) via `pyproject.toml` dependencies. -- Tests are picked up automatically by `ci.yaml` and `ci_includes_e2e_test.yaml` workflows. - -## Automation (`.github/workflows/`) - -Key workflows shipped with the template: - -- **`ci.yaml`** – Standard matrix CI (Python versions, OS variants, linting, tests). -- **`ci_includes_e2e_test.yaml`** – Optional CI variant that demonstrates how to add E2E jobs. -- **`release.yml`** – Intent-driven release process (Python package + Docker + docs). -- **`release-validate.yml`** / **`release-staging.yml`** – Validation/staging runs before production release. -- **`documentation.yaml`** – Builds and publishes Docusaurus site. -- **`type-check.yml`** – PEP 561 type distribution verification using the template’s `src/` package. -- **Supporting workflows** – Docker CI, docs auto-merge, docs build check, etc. - -Use these as blueprints; remove what you do not need or extend them for your environment. - -## Documentation (`docs_with_docusarus/` and `docs_with_mkdocs/`) - -- Docusaurus site is the primary documentation experience with versioning, search, and blog examples. -- MkDocs project is included for teams that prefer a Markdown-first experience without React components. -- Both stacks share the same content philosophyβ€”update whichever matches your needs and disable the other if unnecessary. - -## Scripts (`scripts/`) - -- Holds helper tooling used by CI (e.g., release utilities, documentation helpers). -- Keep reusable automation snippets here so they can be invoked locally and by workflows. - -## Tooling Configuration - -- **`pyproject.toml`** centralizes dependency groups (development, pre-commit) and configures pytest, coverage, pylint, mypy, etc. -- **`uv.lock`** records exact dependency versions resolved by uv; check it in for reproducible builds. -- Pre-commit hooks are declared in `.pre-commit-config.yaml` and reference the same virtual environment produced by uv. - -## Extending the Template - -- **Add packages** – Create new modules under `src/your_package/` and expose them in `__init__.py`. -- **Add CLI entry points** – Configure `[project.scripts]` or `tool.hatch` sections in `pyproject.toml`. -- **Add services** – Introduce FastAPI, Click, or other frameworks and wire tests/workflows accordingly. -- **Add pipelines** – Duplicate existing GitHub workflows or call out to reusable workflows in other repos. - -Keeping this structure consistent makes it easier to upgrade the template, onboard contributors, and reuse automation across multiple projects. diff --git a/docs/contents/development/ci-cd/additional-ci-workflows.mdx b/docs/contents/development/ci-cd/additional-ci-workflows.mdx deleted file mode 100644 index 38eb485..0000000 --- a/docs/contents/development/ci-cd/additional-ci-workflows.mdx +++ /dev/null @@ -1,155 +0,0 @@ ---- -title: Additional CI Workflows -sidebar_position: 6 ---- - -# Additional CI Workflows - -This document covers the specialized CI workflows that support specific aspects of the Python uv template project beyond the main continuous integration and release processes. - -## Overview - -The project includes several specialized CI workflows that handle specific operational tasks: - -- **🐳 Docker CI** - Container image building and testing -- **πŸ“‹ DockerHub README CI** - Repository description synchronization -- **πŸ“š Documentation Build Check** - Validates documentation builds on PRs and branch changes -- **πŸ€– Documentation Auto-Approve & Auto-Merge** - Streamlined docs updates - ---- - -## Docker CI - -[![docker-ci](https://github.com/Chisanan232/Template-Python-UV-Project/actions/workflows/docker-ci.yml/badge.svg)](https://github.com/Chisanan232/Template-Python-UV-Project/actions/workflows/docker-ci.yml) - -The `docker-ci.yml` workflow tests Docker image building and functionality. - -**Triggers:** -- **Push to master**: When Docker-related files change - - GitHub Actions workflow files - - Python source code (`src/**/*.py`) - - Dockerfile and Docker scripts - -**Purpose**: Validates Docker image builds and containerized application functionality. - -**Key Features:** -- Validates Docker image build process -- Tests containerized application functionality -- Ensures Docker configuration correctness -- Separate from the main release Docker builds - ---- - -## DockerHub README CI - -[![dockerhub-readme-ci](https://github.com/Chisanan232/Template-Python-UV-Project/actions/workflows/dockerhub-readme-ci.yml/badge.svg)](https://github.com/Chisanan232/Template-Python-UV-Project/actions/workflows/dockerhub-readme-ci.yml) - -The `dockerhub-readme-ci.yml` workflow updates the Docker Hub repository description. - -**Triggers:** -- **Push to master**: When `README_DOCKERHUB.md` is modified -- **Workflow file changes**: When the DockerHub README workflow itself is updated - -**Purpose**: Keeps Docker Hub repository description synchronized with the documentation. - -**Key Features:** -- Automatic synchronization of Docker Hub repository description -- Triggered by changes to Docker-specific documentation -- Maintains consistency between repository and registry documentation - ---- - -## Documentation Build Check - -[![Documentation Build Check](https://github.com/Chisanan232/Template-Python-UV-Project/actions/workflows/docs-build-check.yaml/badge.svg)](https://github.com/Chisanan232/Template-Python-UV-Project/actions/workflows/docs-build-check.yaml) - -The [`docs-build-check.yaml`](https://github.com/Chisanan232/Template-Python-UV-Project/blob/master/.github/workflows/docs-build-check.yaml) workflow validates that documentation builds successfully whenever documentation-related files are modified. - -**Triggers:** -- **Pull Requests**: Any PR that modifies documentation files -- **Push Events**: All branches except `master` (to avoid conflicts with the main documentation deployment workflow) -- **Path Monitoring**: Automatically detects changes to documentation content, configuration, and dependencies - -**Purpose**: Ensures documentation builds successfully before merging changes, preventing broken documentation deployments. - -**Key Features:** -- **Comprehensive Path Monitoring** - Watches all documentation-related files including content, configuration, dependencies, and assets -- **Fast Build Validation** - Uses optimized setup with shallow clones and dependency caching for quick feedback -- **Build Quality Checks** - Validates build output, critical files, and provides detailed build statistics -- **TypeScript Validation** - Runs type checking to catch configuration errors early -- **Concurrency Control** - Cancels in-progress runs for the same PR/branch to save resources -- **Detailed Reporting** - Provides comprehensive build summaries in GitHub Actions interface - -**Build Process:** -1. **Environment Setup**: Node.js 22 + pnpm 10 (matching production deployment) -2. **Dependency Installation**: Uses frozen lockfile for consistency -3. **Type Checking**: Validates TypeScript configuration and content -4. **Documentation Build**: Executes full Docusaurus build process -5. **Quality Validation**: Checks build artifacts and critical files -6. **Build Reporting**: Provides detailed statistics and status summary - -**Path Coverage:** -- CI workflow configurations (`.github/workflows/docs-build-check.yaml`, `documentation.yaml`) -- Dependencies (`package.json`, `pnpm-lock.yaml`) -- Configuration files (`docusaurus.config.ts`, `tsconfig.json`) -- Content files (`.md`, `.mdx`, `.ts`, `.tsx`, `.js`, `.jsx`, `.css`) -- Versioned content and sidebars -- Static assets and source files - -**Safety Mechanisms:** -- Prevents conflicts with main documentation deployment workflow -- Uses frozen lockfile installation for reproducible builds -- Validates critical files existence (index.html, 404.html) -- Provides warnings for potential build issues -- Includes comprehensive error reporting and debugging information - ---- - -## Documentation Auto-Approve & Auto-Merge - -[![Docs-only auto-approve & automerge](https://github.com/Chisanan232/Template-Python-UV-Project/actions/workflows/docs-automerge.yml/badge.svg)](https://github.com/Chisanan232/Template-Python-UV-Project/actions/workflows/docs-automerge.yml) - -The `docs-automerge.yml` workflow automatically approves and merges pull requests that only contain documentation changes. This streamlines the process for documentation updates. - -**Triggers:** -- **Pull requests to master**: For PRs containing only documentation changes -- **PR events**: `opened`, `reopened`, `synchronize`, `ready_for_review` - -**Purpose**: Accelerates documentation updates by automating approval and merge for docs-only changes. - -**Key Features:** -- Intelligent detection of documentation-only changes -- Automated approval and merge for qualifying PRs -- Safety checks to ensure only documentation files are modified -- Streamlined workflow for maintaining up-to-date documentation - -**Safety Mechanisms:** -- Validates that PR contains only documentation file changes -- Requires all status checks to pass before auto-merge -- Maintains audit trail of automated actions - ---- - -## Workflow Integration - -These additional CI workflows integrate with the main CI/CD system: - -### **Integration Points:** -- **Docker CI** β†’ Validates containers before release workflows -- **DockerHub README** β†’ Ensures registry documentation stays current -- **Documentation Build Check** β†’ Validates docs builds on PRs to prevent broken deployments -- **Docs Auto-merge** β†’ Accelerates documentation maintenance - -### **Monitoring and Maintenance:** -- All workflows include status badges for easy monitoring -- Failed workflows trigger notifications for immediate attention -- Regular review ensures workflows stay aligned with project needs - ---- - -## Navigation - -- **🏠 [CI/CD Overview](./index.mdx)** - Return to main CI/CD hub -- **πŸ“‹ [Continuous Integration](./continuous-integration.mdx)** - Main CI workflows and testing -- **πŸ”„ [Release System](./release-system.mdx)** - Production releases and deployment -- **πŸ› οΈ [Developer Guide](./developer-guide.mdx)** - Configuration and troubleshooting diff --git a/docs/contents/development/ci-cd/continuous-integration.mdx b/docs/contents/development/ci-cd/continuous-integration.mdx deleted file mode 100644 index ba88d57..0000000 --- a/docs/contents/development/ci-cd/continuous-integration.mdx +++ /dev/null @@ -1,384 +0,0 @@ ---- -id: continuous-integration -title: Continuous Integration -sidebar_position: 1 ---- - -```mdx-code-block -import TOCInline from '@theme/TOCInline'; -``` - -# Continuous Integration - -![Modular CI](https://img.shields.io/badge/CI-Modular%20%26%20Flexible-brightgreen?style=for-the-badge) -![Multi-Platform](https://img.shields.io/badge/Testing-Multi--Platform%20%26%20Multi--Version-blue?style=for-the-badge) -![Comprehensive](https://img.shields.io/badge/Coverage-5%20Test%20Types-orange?style=for-the-badge) - -The Python UV template features a **comprehensive, modular CI system** that supports flexible testing configurations, multi-platform compatibility, and extensive test coverage reporting. The architecture is designed for scalability and ease of maintenance. - - - -## Status Badges - -[![CI](https://github.com/Chisanan232/Template-Python-UV-Project/actions/workflows/ci.yaml/badge.svg)](https://github.com/Chisanan232/Template-Python-UV-Project/actions/workflows/ci.yaml) -[![CI + E2E](https://github.com/Chisanan232/Template-Python-UV-Project/actions/workflows/ci_includes_e2e_test.yaml/badge.svg)](https://github.com/Chisanan232/Template-Python-UV-Project/actions/workflows/ci_includes_e2e_test.yaml) - -## CI Workflow Architecture - -The new CI system features a **3-tier modular architecture** that provides maximum flexibility and maintainability: - -```mermaid -graph TD - A[Main CI Workflows] --> B[ci.yaml - Regular CI] - A --> C[ci_includes_e2e_test.yaml - E2E CI] - - B --> D[rw_run_all_test_and_record.yaml] - C --> D - - D --> E[rw_build_and_test.yaml] - D --> F[Coverage Reporting Jobs] - - E --> G[rw_uv_run_test_with_multi_py_versions.yaml] - E --> H[5 Test Types] - - G --> I[Multi-Platform Matrix] - G --> J[Multi-Python Version Matrix] - - H --> K[Unit Tests] - H --> L[Integration Tests] - H --> M[E2E Tests] - H --> N[Contract Tests] - H --> O[CI Script Tests] - - F --> P[Codecov Upload] - F --> Q[SonarCloud Scan] - - style A fill:#4CAF50 - style D fill:#2196F3 - style E fill:#FF9800 - style G fill:#9C27B0 -``` - -### Architecture Benefits - -βœ… **Modular Design**: Clear separation of concerns across workflow layers -βœ… **Flexible Configuration**: Configurable Python versions and operating systems -βœ… **Comprehensive Testing**: 5 different test types with matrix execution -βœ… **Multi-Platform Support**: Ubuntu (latest, 22.04) and macOS (latest, 14) -βœ… **Scalable**: Easy to add new test types or platforms -βœ… **Maintainable**: Single workflow changes affect all consuming workflows - -## Workflow Triggers & Configuration - -### Main CI Workflow (`ci.yaml`) - -**Triggers:** -- **Push to base branch**: Excluding branches with "e2e" in their name -- **Pull requests to base branch**: Excluding branches with "e2e" in their name -- **Path-based filtering**: Only triggers when relevant files change - -**Monitored Paths:** -```yaml -# GitHub Actions workflows -- ".github/workflows/ci.yaml" -- ".github/workflows/rw_build_and_test.yaml" -- ".github/workflows/rw_run_all_test_and_record.yaml" - -# Source code and tests -- "/**/*.py" -- "test/**/*.py" - -# Configuration files -- ".coveragerc", "codecov.yml", "pytest.ini" -- "sonar-project.properties" -- "pyproject.toml", "uv.lock" -``` - -### E2E CI Workflow (`ci_includes_e2e_test.yaml`) - -**Triggers:** -- **Push to E2E branches**: Branches containing "e2e" in their name -- **Manual dispatch**: For on-demand E2E testing -- **Scheduled runs**: Optional cron schedule for regular E2E validation - -**Key Features:** -- Includes all regular CI tests **plus** end-to-end testing -- Uses Slack bot token for E2E API testing -- Comprehensive coverage including external service integration - -## Detailed Workflow Components - -### Tier 1: Main CI Entry Points - -#### 1. Regular CI (`ci.yaml`) -```yaml -jobs: - build-and-test_all: - uses: ./.github/workflows/rw_run_all_test_and_record.yaml - secrets: - codecov_token: ${{ secrets.CODECOV_TOKEN }} - sonar_token: ${{ secrets.SONAR_TOKEN }} -``` -- **Purpose**: Standard development CI without E2E tests -- **Optimized**: Faster execution for regular development workflow -- **Coverage**: Unit, integration, contract, and CI script tests - -#### 2. E2E-Enabled CI (`ci_includes_e2e_test.yaml`) -```yaml -jobs: - build-and-test_all: - uses: ./.github/workflows/rw_run_all_test_and_record.yaml - with: - run_e2e: true - secrets: - e2e_test_api_token: ${{ secrets.SLACK_BOT_TOKEN }} - codecov_token: ${{ secrets.CODECOV_TOKEN }} - sonar_token: ${{ secrets.SONAR_TOKEN }} -``` -- **Purpose**: Comprehensive testing including end-to-end scenarios -- **Integration**: External API testing with Slack bot integration -- **Usage**: E2E development branches and validation - -### Tier 2: Test Orchestration (`rw_run_all_test_and_record.yaml`) - -**Core Functionality:** -- **Coordinates** all testing phases and coverage reporting -- **Manages** dependencies between test execution and reporting -- **Handles** conditional E2E test execution -- **Integrates** with external coverage and quality tools - -**Key Features:** -```yaml -inputs: - run_e2e: - description: "Enable end-to-end testing" - type: boolean - default: false - -secrets: - e2e_test_api_token: "Slack bot token for E2E tests" - codecov_token: "Codecov API token" - sonar_token: "SonarCloud API token" -``` - -**Workflow Jobs:** -1. **`build-and-test`**: Executes all test suites via `rw_build_and_test.yaml` -2. **Coverage Upload Jobs**: Individual coverage reports for each test type -3. **`sonarcloud_finish`**: Code quality analysis and reporting - -### Tier 3: Core Testing Engine (`rw_build_and_test.yaml`) - -**Comprehensive Test Suite Execution:** - -#### Test Types Supported - -| Test Type | Folder | Description | Parallel Execution | -|-----------|---------|-------------|-----------------| -| **Unit Tests** | `./test/unit_test` | Component-level testing | Full matrix | -| **Integration Tests** | `./test/integration_test` | Multi-component testing | Full matrix | -| **E2E Tests** | `./test/e2e_test` | End-to-end scenarios | Sequential (`max-parallel: 1`) | -| **Contract Tests** | `./test/contract_test` | API contract validation | Full matrix | -| **CI Script Tests** | `./test/ci_script_test` | CI infrastructure testing | Full matrix | - -#### Configuration Matrix - -**Python Versions (Configurable):** -```yaml -python-versions: '["3.13"]' # Default, easily configurable -``` - -**Operating Systems (Multi-Platform):** -```yaml -operating-systems: '[ - "ubuntu-latest", - "ubuntu-22.04", - "macos-latest", - "macos-14" -]' -``` - -### Tier 4: Multi-Platform Test Execution (`rw_uv_run_test_with_multi_py_versions.yaml`) - -**Enhanced Features (New):** -- βœ… **Configurable Python Versions**: JSON array input for flexible Python version testing -- βœ… **Configurable Operating Systems**: JSON array input for multi-platform support -- βœ… **Matrix Strategy**: Full combinatorial testing across Python versions and OS platforms -- βœ… **Dependency Group Support**: UV-based dependency management with group installation -- βœ… **API Integration Testing**: Slack bot token validation for E2E tests - -**Configuration Options:** -```yaml -inputs: - python-versions: - description: "JSON array of Python versions to test against" - default: '["3.13"]' - operating-systems: - description: "JSON array of operating systems to test on" - default: '["ubuntu-latest", "ubuntu-22.04", "macos-latest", "macos-14"]' - test_type: "Specific test type (unit-test, integration-test, etc.)" - test_folder: "Target test folder path" - install_dependency_with_group: "UV dependency group for installation" - max-parallel: "Maximum parallel jobs (default: 0 = unlimited)" -``` - -## Advanced Configuration - -### Python Version Flexibility - -**Single Version (Fast CI):** -```yaml -python-versions: '["3.13"]' -``` - -**Multi-Version (Compatibility Testing):** -```yaml -python-versions: '["3.11", "3.12", "3.13"]' -``` - -### Operating System Flexibility - -**Ubuntu Only (Fast CI):** -```yaml -operating-systems: '["ubuntu-latest"]' -``` - -**Full Cross-Platform:** -```yaml -operating-systems: '[ - "ubuntu-latest", - "ubuntu-22.04", - "macos-latest", - "macos-14", - "windows-latest" -]' -``` - -## Coverage Reporting Integration - -### Codecov Integration - -**Per-Test-Type Coverage:** -- **Unit Tests**: `codecov_flags: unit-test` -- **Integration Tests**: `codecov_flags: integration-test` -- **E2E Tests**: `codecov_flags: e2e-test` -- **Contract Tests**: `codecov_flags: contract-test` -- **All Tests Combined**: `codecov_flags: all-test` - -### SonarCloud Integration - -**Code Quality Metrics:** -- **Static Analysis**: Code complexity, maintainability -- **Security**: Vulnerability detection and security hotspots -- **Reliability**: Bug detection and code smells -- **Coverage**: Integration with test coverage data - -## Best Practices & Usage - -### Development Workflow - -**Regular Development (Fast CI):** -1. Create feature branch from base branch -2. Push commits trigger `ci.yaml` workflow -3. Fast execution with core test suite (excludes E2E) -4. Coverage reports uploaded to Codecov -5. Code quality checked by SonarCloud - -**E2E Development:** -1. Create branch with "e2e" in name (e.g., `feature-e2e`, `e2e-api-testing`) -2. Push commits trigger `ci_includes_e2e_test.yaml` workflow -3. Comprehensive testing including external API integration -4. Full coverage including E2E scenarios - -### Configuration for Child Projects - -**Step 1: Update Branch Names** -```yaml -# In ci.yaml and ci_includes_e2e_test.yaml -branches: - - "main" # Change from "" -``` - -**Step 2: Update Package Name** -```yaml -# In ci.yaml paths section -paths: - - "your_package/**/*.py" # Change from "" -``` - -**Step 3: Configure Secrets** -```yaml -# Repository secrets needed: -CODECOV_TOKEN: "Your Codecov token" -SONAR_TOKEN: "Your SonarCloud token" -SLACK_BOT_TOKEN: "Your Slack bot token (for E2E tests)" -``` - -**Step 4: Customize Test Matrix (Optional)** -```yaml -# In rw_build_and_test.yaml, modify for your needs: -python-versions: '["3.11", "3.12", "3.13"]' # Add more Python versions -operating-systems: '["ubuntu-latest", "macos-latest"]' # Reduce OS matrix if needed -``` - -### Performance Optimization - -**Fast CI Strategy:** -- Use single Python version for regular CI -- Limit OS matrix to essential platforms -- Run E2E tests only on dedicated branches -- Use `max-parallel` settings appropriately - -**Comprehensive CI Strategy:** -- Multi-Python version testing for compatibility -- Full OS matrix for cross-platform validation -- Include E2E tests in regular workflow -- Enable scheduled runs for continuous validation - -### Troubleshooting - -**Common Issues:** - -1. **Test Matrix Too Large** - - **Symptom**: CI takes too long or hits GitHub Actions limits - - **Solution**: Reduce Python versions or OS matrix - - **Example**: Use `python-versions: '["3.13"]'` and `operating-systems: '["ubuntu-latest"]'` - -2. **E2E Tests Failing** - - **Symptom**: E2E workflow fails with authentication errors - - **Solution**: Verify `SLACK_BOT_TOKEN` secret is properly configured - - **Check**: Ensure bot token has necessary permissions - -3. **Coverage Upload Issues** - - **Symptom**: Codecov upload fails or shows incomplete coverage - - **Solution**: Verify `CODECOV_TOKEN` secret and check coverage file generation - - **Debug**: Enable debug logging in coverage upload step - -4. **Dependency Installation Failures** - - **Symptom**: UV dependency installation fails - - **Solution**: Check `pyproject.toml` dependency groups and UV lock file - - **Fix**: Ensure dependency group (`dev`) exists and is properly configured - -### Migration Guide - -**From Legacy CI:** -1. **Replace** old CI workflows with new modular architecture -2. **Update** branch and package name references -3. **Configure** repository secrets for external integrations -4. **Test** both regular and E2E workflows -5. **Optimize** matrix configuration for your project needs - -**Benefits After Migration:** -- βœ… **Faster CI**: Separate regular and E2E workflows -- βœ… **More Flexible**: Configurable Python versions and OS platforms -- βœ… **Better Organized**: Clear separation of test types -- βœ… **Comprehensive Coverage**: 5 test types with detailed reporting -- βœ… **Easier Maintenance**: Modular architecture simplifies updates - ---- - -## Navigation - -- **🏠 [CI/CD Overview](./index.mdx)** - Return to main CI/CD hub -- **πŸ”„ [Release System](./release-system.mdx)** - Learn about releases and deployment -- **βš™οΈ [Additional CI Workflows](./additional-ci-workflows.mdx)** - Specialized utility workflows -- **πŸ› οΈ [Developer Guide](./developer-guide.mdx)** - Configuration and troubleshooting diff --git a/docs/contents/development/ci-cd/developer-guide.mdx b/docs/contents/development/ci-cd/developer-guide.mdx deleted file mode 100644 index 76e1f40..0000000 --- a/docs/contents/development/ci-cd/developer-guide.mdx +++ /dev/null @@ -1,531 +0,0 @@ ---- -title: Developer Guide -sidebar_position: 6 ---- - -import TOCInline from '@theme/TOCInline'; - -# Developer Guide & Additional Workflows - -![Developer Tools](https://img.shields.io/badge/Developer-Friendly-blue?style=for-the-badge) -![Best Practices](https://img.shields.io/badge/Guide-Best%20Practices-green?style=for-the-badge) -![Specialized Workflows](https://img.shields.io/badge/Workflows-Specialized-orange?style=for-the-badge) - -This guide provides comprehensive information for developers working with the Python uv template project CI/CD system, including troubleshooting, configuration management, specialized workflows, and best practices. - - - -## Using the Release System - -### Configuring a Release - -Edit `.github/tag_and_release/intent.yaml` to configure your release: - -```yaml -# Example: Patch release with selective docs versioning -release: true -level: "patch" -artifacts: - python: "auto" - docker: "auto" - docs: - mode: "auto" - sections: ["docs", "dev"] # Only version docs and dev sections - strategy: "changed" # Only version if changes detected -notes: "Patch release with selective documentation versioning" -``` - -### Triggering Releases - -#### Automatic Release (Push to master) -```bash -git push origin master -# Triggers release workflow automatically -``` - -#### Manual Release (GitHub UI) -1. Go to Actions β†’ Release -2. Click "Run workflow" -3. Optionally override intent configuration - -#### Manual Release (CLI) -```bash -# Trigger release workflow manually -gh workflow run release.yml - -# Trigger with custom parameters -gh workflow run release.yml \ - --field release=true \ - --field level=patch \ - --field notes="Manual patch release" -``` - -### Pre-Release Validation - -#### For Pull Requests -- Release validation runs automatically on PRs to master -- Provides comprehensive validation without publishing -- Reviews security scan results and vulnerability reports - -#### Manual Validation -```bash -# Trigger validation workflow manually -gh workflow run release-validate.yml - -# Check validation status -gh run list --workflow=release-validate.yml --limit=5 -``` - -### Staging Releases - -#### Deploy to Staging -```bash -# Manual staging release -gh workflow run release-staging.yml - -# Check staging status -gh run list --workflow=release-staging.yml --limit=3 -``` - -#### Staging Artifacts -- **TestPyPI**: `pip install -i https://test.pypi.org/simple/ test-python-uv-project-template` -- **GHCR Staging**: `docker pull ghcr.io/Chisanan232/Template-Python-UV-Project:1.0.0-rc.0` -- **Preview Docs**: Available on docs-preview branch - -## Common Workflows - -### Release Preparation - -1. **Update Code**: Make your changes and ensure tests pass -2. **Configure Intent**: Set release configuration in `intent.yaml` -3. **Validate**: Create PR and review validation results -4. **Stage** (Optional): Test in staging environment -5. **Release**: Merge to master for automatic release - -### Hotfix Release Process - -```bash -# 1. Create hotfix branch from master -git checkout master -git checkout -b hotfix/critical-fix - -# 2. Make necessary changes -# ... make fixes ... - -# 3. Configure for patch release -cat > .github/tag_and_release/intent.yaml << EOF -release: true -level: patch -artifacts: - python: force - docker: force - docs: skip -notes: "Hotfix: Critical security vulnerability" -EOF - -# 4. Commit and push -git add . -git commit -m "fix: critical security vulnerability" -git push origin hotfix/critical-fix - -# 5. Create PR and validate -gh pr create --title "Hotfix: Critical security fix" --body "Emergency patch release" - -# 6. After validation passes, merge to master -gh pr merge --merge -``` - -### Feature Release Process - -```bash -# 1. Develop feature in branch -git checkout -b feature/new-capability - -# 2. After development, configure for minor release -cat > .github/tag_and_release/intent.yaml << EOF -release: true -level: minor -artifacts: - python: auto - docker: auto - docs: - mode: auto - sections: ["docs", "dev"] - strategy: changed -notes: "New feature: Enhanced API capabilities" -EOF - -# 3. Create PR for validation -gh pr create --title "feat: new API capabilities" --body "Adds new features with docs" - -# 4. Test in staging first -gh workflow run release-staging.yml - -# 5. After staging validation, merge to master -gh pr merge --merge -``` - -## Troubleshooting - -### Git Synchronization Issues - -**Symptoms**: Artifacts built with old version (0.0.0) instead of bumped version (0.0.1) - -**Root Cause**: Downstream jobs used `actions/checkout@v5` without `ref` parameter, defaulting to original commit SHA instead of latest commit with version bump. - -**Solution Applied**: All workflows now use `ref: ${{ github.ref_name }}` to checkout latest branch state. - -**Fixed Workflows**: -- `rw_python_package.yaml` - Python package operations -- `rw_docker_operations.yaml` - Docker image operations -- `rw_docs_operations.yaml` - Documentation operations -- `rw_build_git-tag_and_create_github-release.yaml` - Git tagging -- `release-staging.yml` - Staging releases - -**Impact**: Python packages, Docker images, and docs now use correct bumped version - -### UV Lock File Synchronization - -**Enhancement**: Version bump now automatically updates `uv.lock` file to maintain dependency synchronization - -**Process**: -1. After `uv version --bump`, the workflow runs `uv lock` to update lock file -2. Both `pyproject.toml` and `uv.lock` are committed together in version bump -3. Ensures dependency lock file stays in sync with version changes - -### Documentation Versioning Issues - -**Problem**: Documentation not updating after release -**Solutions**: -- Verify `sections` configuration matches actual docs structure -- Use `strategy: "always"` to force versioning regardless of changes -- Check that Docusaurus plugin IDs in `sections` array exist in `docusaurus.config.ts` - -**Problem**: Guard job failing -**Solutions**: -- Check that release workflow uploaded the `release-docs-flag` artifact -- Verify artifact download permissions are correct -- Ensure workflow run ID is accessible - -### Intent Configuration Issues - -**Validation**: Configuration is validated against JSON schema during parsing -**Error Handling**: Invalid configurations fail with descriptive error messages -**Testing**: Use `release-validate.yml` workflow to test configuration changes - -### Common Configuration Mistakes - -#### 1. Incorrect Section Names -```yaml -# ❌ Wrong - section doesn't exist -docs: - sections: ["documentation", "developer"] - -# βœ… Correct - matches Docusaurus config -docs: - sections: ["docs", "dev"] -``` - -#### 2. Conflicting Mode and Strategy -```yaml -# ❌ Confusing - mode skip overrides strategy -docs: - mode: skip - strategy: always # This has no effect - -# βœ… Clear intent -docs: - mode: auto - strategy: always -``` - -#### 3. Legacy vs Enhanced Format Mixing -```yaml -# ❌ Wrong - can't mix formats -docs: auto -docs: - sections: ["docs"] - -# βœ… Choose one format consistently -docs: - mode: auto - sections: ["docs", "dev"] - strategy: changed -``` - -### Tag Mismatch Issues - -**Diagnosis**: -- Check that Docker build and security scan jobs use consistent tags -- Validation workflow includes defensive checks to catch this early - -**Solutions**: -```bash -# Verify tag consistency across jobs -gh run view --log | grep -E "(image-tag|docker tag)" -``` - -### SBOM Generation Failures - -**Fallback Mechanism**: System includes fallback SBOM generation from workspace -**Debugging**: Check security scan artifacts for detailed logs - -**Common Issues**: -- Docker image not accessible for scanning -- Syft version compatibility -- Workspace permission issues - -## Monitoring Releases - -### Release Status Monitoring - -**Primary Workflows**: -- [Release Workflow](https://github.com/Chisanan232/Template-Python-UV-Project/actions/workflows/release.yml) -- [Validation Results](https://github.com/Chisanan232/Template-Python-UV-Project/actions/workflows/release-validate.yml) - -**CLI Monitoring**: -```bash -# Monitor active release -gh run list --workflow=release.yml --limit=1 - -# Check specific run -gh run view - -# Monitor in real-time -gh run watch -``` - -### Security Reports - -**Review Process**: -- Review vulnerability scan results in workflow summaries -- Download security artifacts for detailed analysis -- Monitor CVE reports and remediation recommendations - -**Artifact Access**: -```bash -# Download security artifacts -gh run download --name security-reports - -# View SBOM -cat sbom.spdx.json | jq '.packages[] | select(.name | contains("critical"))' -``` - -### Artifact Verification - -#### Python Package (PyPI) -```bash -# Check package availability and correct version -pip install test-python-uv-project-template== -python -c "import test-python-uv-project-template; print(test-python-uv-project-template.__version__)" -``` - -#### Docker Hub -```bash -# Verify Docker image availability and correct version tags -docker pull chisanan232/test-python-uv-project-template: -docker run --rm chisanan232/test-python-uv-project-template: --version -``` - -#### GitHub Container Registry (GHCR) -```bash -# Verify Docker image availability and correct version tags -docker pull ghcr.io/chisanan232/test-python-uv-project-template: -docker run --rm ghcr.io/chisanan232/test-python-uv-project-template: --version -``` - -#### Documentation -```bash -# Check versioned documentation is available -curl -s https://chisanan232.github.io/test-python-uv-project-template/docs// -``` - -#### Version Consistency Verification -All artifacts should reflect the same bumped version: -- Verify Python package, both Docker registries, and docs use identical version tags -- Cross-check that no artifacts still reference the old version (e.g., 0.0.0 vs 0.0.1) - -## Additional CI Workflows - -### Docker CI - -[![docker-ci](https://github.com/Chisanan232/Template-Python-UV-Project/actions/workflows/docker-ci.yml/badge.svg)](https://github.com/Chisanan232/Template-Python-UV-Project/actions/workflows/docker-ci.yml) - -**Purpose**: Standalone Docker image building and functionality testing - -**Features**: -- Independent Docker image testing -- Multi-architecture build validation -- Container functionality verification -- Performance and resource usage testing - -**Use Cases**: -- Testing Docker changes without full release -- Validating Dockerfile modifications -- Performance regression testing - -### DockerHub README CI - -[![dockerhub-readme-ci](https://github.com/Chisanan232/Template-Python-UV-Project/actions/workflows/dockerhub-readme-ci.yml/badge.svg)](https://github.com/Chisanan232/Template-Python-UV-Project/actions/workflows/dockerhub-readme-ci.yml) - -**Purpose**: Updates the Docker Hub repository description automatically - -**Features**: -- Synchronizes README content with Docker Hub -- Maintains consistent documentation across platforms -- Automatic updates on documentation changes - -**Benefits**: -- Keeps Docker Hub page current with latest documentation -- Reduces manual maintenance overhead -- Ensures users see accurate information - -### Documentation Auto-Approve & Auto-Merge - -[![docs-automerge](https://github.com/Chisanan232/Template-Python-UV-Project/actions/workflows/docs-automerge.yml/badge.svg)](https://github.com/Chisanan232/Template-Python-UV-Project/actions/workflows/docs-automerge.yml) - -**Purpose**: Streamlines documentation-only pull request processing - -#### Features - -**1. Identifying Documentation-Only Changes**: -- Uses path filtering to detect changes limited to documentation files -- Checks that no code, configuration, or infrastructure files are modified -- Validates PR scope to ensure safety of automated processing - -**2. Automatic Processing**: -- Adds a "πŸ“ docs-only" label to qualifying PRs -- Automatically approves the PR with a review comment -- Enables auto-merge functionality (merge commit) - -#### Workflow Process - -```mermaid -graph TD - A[PR Created/Updated] --> B[Check File Changes] - B --> C{Documentation Only?} - C -->|Yes| D[Add docs-only Label] - C -->|No| E[Skip Automation] - D --> F[Auto-approve PR] - F --> G[Enable Auto-merge] - G --> H[PR Merged Automatically] -``` - -#### Requirements for Auto-Merge - -**Repository Settings**: -- Repository must have "Allow auto-merge" enabled in settings -- Repository must have "Allow GitHub Actions to create and approve pull requests" enabled - -**PR Requirements**: -- PR must not be in draft state -- Changes must be limited to documentation files -- All other CI checks must pass - -**Benefits**: -- Reduces maintenance burden for documentation-focused contributions -- Maintains proper review processes for code changes -- Accelerates documentation improvement cycle - -## CI/CD Configuration Files - -All CI/CD workflows are defined in the `.github/workflows/` directory: - -### Core Workflows -- `ci.yaml` - Main CI workflow with comprehensive testing -- `release.yml` - Modern intent-driven release system -- `release-validate.yml` - Pre-release validation workflow -- `release-staging.yml` - Staging environment deployment -- `documentation.yaml` - Documentation building and deployment - -### Specialized Workflows -- `docker-ci.yml` - Standalone Docker testing -- `dockerhub-readme-ci.yml` - DockerHub README synchronization -- `docs-automerge.yml` - Documentation PR automation - -**Browse All Workflows**: [Workflow Definitions](https://github.com/Chisanan232/Template-Python-UV-Project/tree/master/.github/workflows) - -## Best Practices for Contributors - -### Development Workflow - -#### 1. Pre-Submission Testing -```bash -# Run tests locally before submitting PR -uv run pytest -uv run mypy src/ -uv run ruff check src/ - -# Test Docker build locally -docker build -t test-image . -docker run --rm test-image --version -``` - -#### 2. CI/CD Integration -- **Monitor CI Results**: Check CI status on PRs immediately after submission -- **Address Failures Promptly**: Fix failing tests or code quality issues quickly -- **Use Validation Workflows**: Run `release-validate.yml` to test release changes - -#### 3. Documentation Standards -- **Update Documentation**: Keep docs in sync with code changes -- **Test Documentation Builds**: Verify docs build successfully locally -- **Use Auto-merge**: Leverage docs-only PR automation for pure documentation changes - -### Configuration Management - -#### 4. Release Configuration -```yaml -# Conservative approach (recommended) -release: true -level: auto # Let commit messages determine bump level -artifacts: - python: auto # Only publish if Python files changed - docker: auto # Only publish if Docker files changed - docs: - mode: auto - strategy: changed # Only version changed doc sections -``` - -#### 5. Testing Strategy -- **Staging First**: Use staging releases for major changes -- **Validation Always**: Run validation on all PRs to master -- **Security Reviews**: Monitor security scan results regularly - -### Quality Assurance - -#### 6. Code Quality -- **Maintain Test Coverage**: Add tests for new features to maintain high coverage -- **Follow Code Standards**: Use consistent formatting and linting -- **Document APIs**: Keep API documentation current with implementation - -#### 7. Security Practices -- **Review Vulnerability Reports**: Address security findings promptly -- **Update Dependencies**: Keep dependencies current for security patches -- **Validate Artifacts**: Verify published artifacts work as expected - -### Collaboration Guidelines - -#### 8. Pull Request Best Practices -- **Clear Descriptions**: Provide comprehensive PR descriptions -- **Small Focused Changes**: Keep PRs focused on specific improvements -- **Test Instructions**: Include testing steps for reviewers - -#### 9. Issue Management -- **Reproducible Examples**: Provide clear reproduction steps for bugs -- **Feature Requests**: Include use cases and implementation suggestions -- **Documentation Issues**: Tag with appropriate labels for quick processing - -### Performance Optimization - -#### 10. Workflow Efficiency -- **Cache Usage**: Leverage caching for faster builds -- **Parallel Jobs**: Use matrix strategies for parallel testing -- **Resource Management**: Choose appropriate runner sizes for different jobs - ---- - -πŸ”— **Related Documentation**: -- [Release System](./release-system.mdx) - Comprehensive release workflow configuration -- [Documentation Deployment](./documentation-deployment.mdx) - Documentation workflow architecture -- [Reusable Workflows](./reusable-workflows.mdx) - Understanding the modular workflow components -- [CI/CD Overview](./index.mdx) - Navigate to other CI/CD documentation sections diff --git a/docs/contents/development/ci-cd/documentation-deployment.mdx b/docs/contents/development/ci-cd/documentation-deployment.mdx deleted file mode 100644 index aadbc1b..0000000 --- a/docs/contents/development/ci-cd/documentation-deployment.mdx +++ /dev/null @@ -1,466 +0,0 @@ ---- -title: Documentation Deployment -sidebar_position: 4 ---- - -import TOCInline from '@theme/TOCInline'; - -# Documentation Deployment - -![Documentation Workflow](https://img.shields.io/badge/Workflow-Dual%20Trigger-blue?style=for-the-badge) -![GitHub Pages](https://img.shields.io/badge/Deploy-GitHub%20Pages-orange?style=for-the-badge) -![Docusaurus](https://img.shields.io/badge/Built%20With-Docusaurus-green?style=for-the-badge) - -[![documentation](https://github.com/Chisanan232/Template-Python-UV-Project/actions/workflows/documentation.yaml/badge.svg)](https://github.com/Chisanan232/Template-Python-UV-Project/actions/workflows/documentation.yaml) - -The documentation workflow (`documentation.yaml`) handles building and deploying project documentation using **dual trigger mechanisms** to ensure reliable deployment after releases. This system solves critical GitHub Actions limitations for automated documentation updates during releases. - - - -## Overview - -The documentation deployment system features: - -- **Dual Trigger Architecture**: Handles both direct documentation changes and release-triggered updates -- **Workflow Run Pattern**: Solves GitHub Actions `GITHUB_TOKEN` commit limitation -- **Intelligent Guard Jobs**: Conditional deployment based on actual documentation changes -- **Artifact-Based Communication**: Reliable cross-workflow communication via artifacts -- **GitHub Pages Integration**: Automated deployment to GitHub Pages with Docusaurus - -## Advanced Trigger Architecture - -The documentation workflow uses a **sophisticated dual-trigger system** to solve the GitHub Actions limitation where `GITHUB_TOKEN` commits don't trigger other workflows: - -### 1. Direct Push Trigger (Traditional) -```yaml -on: - push: - branches: ["master"] - paths: - - "docs/**" - - "*.md" - - "README*.md" - - ".github/workflows/documentation.yaml" - - ".github/workflows/release.yml" - - ".github/workflows/release-*.yml" - - ".github/workflows/rw_*.yaml" - - ".github/tag_and_release/**" -``` - -**Purpose**: Handles direct documentation changes pushed to master branch - -**Triggers On**: -- Documentation file changes -- Workflow file changes that affect release processes -- Configuration changes that impact documentation - -### 2. Workflow Run Trigger (Release Integration) -```yaml -on: - workflow_run: - workflows: ["release"] - types: [completed] - branches: ["master"] -``` - -**Purpose**: Automatically triggers after release workflow completion to handle documentation updates made during version bumps - -## Workflow Run Pattern Implementation - -### Problem Solved - -**GitHub Actions Limitation**: GitHub Actions doesn't trigger workflows on commits made by `GITHUB_TOKEN` (used in release workflows) to prevent infinite loops. This caused documentation workflow to never trigger after release workflow commits that updated documentation files. - -**Impact**: Documentation would become stale after releases because version references in docs weren't being deployed. - -### Solution Architecture - -```mermaid -graph TD - A[Release Workflow] --> B[Bump Version & Update Docs] - B --> C[Set DOCS_UPDATED Flag] - C --> D[Upload Flag Artifact] - D --> E[Documentation Workflow Triggered] - E --> F[Guard Job: Check Flag] - F --> G{Docs Updated?} - G -->|Yes| H[Deploy Documentation] - G -->|No| I[Skip Deployment] - - J[Direct Doc Push] --> H -``` - -### Guard Job Implementation - -The documentation workflow includes an intelligent **guard job** that provides conditional deployment logic: - -#### Guard Job Logic - -```yaml -check_docs_changes: - if: github.event_name == 'workflow_run' - runs-on: ubuntu-latest - outputs: - should_deploy: ${{ steps.check_flag.outputs.should_deploy }} - steps: - - name: Download docs update flag from release workflow - uses: actions/download-artifact@v4 - with: - name: release-docs-flag - run-id: ${{ github.event.workflow_run.id }} - - - name: Check release workflow success and docs update flag - id: check_flag - run: | - # Verify release workflow succeeded - if [[ "${{ github.event.workflow_run.conclusion }}" != "success" ]]; then - echo "Release workflow did not succeed. Skipping documentation deployment." - echo "should_deploy=false" >> $GITHUB_OUTPUT - exit 0 - fi - - # Read docs update flag from artifact - DOCS_UPDATED=$(cat docs_updated.txt) - echo "Documentation update flag: $DOCS_UPDATED" - - if [[ "$DOCS_UPDATED" == "true" ]]; then - echo "Documentation was updated during release. Proceeding with deployment." - echo "should_deploy=true" >> $GITHUB_OUTPUT - else - echo "No documentation updates detected. Skipping deployment." - echo "should_deploy=false" >> $GITHUB_OUTPUT - fi -``` - -#### Guard Job Functions - -1. **Downloads Release Artifacts**: Retrieves the `DOCS_UPDATED` flag from the completed release workflow -2. **Verifies Release Success**: Ensures the release workflow completed successfully -3. **Evaluates Update Flag**: Checks if documentation files were actually updated during the release -4. **Controls Deployment**: Only proceeds with documentation deployment if docs were updated - -### Conditional Deployment Logic - -The main deployment job runs conditionally based on the trigger type: - -```yaml -deploy_documentation: - # Run for direct push OR workflow_run with docs changes - if: | - github.event_name == 'push' || - (github.event_name == 'workflow_run' && needs.check_docs_changes.outputs.should_deploy == 'true') - needs: [check_docs_changes] - runs-on: ubuntu-latest -``` - -**Deployment Conditions**: -- **Direct Push Events**: Always deploy (traditional behavior) -- **Workflow Run Events**: Only deploy if guard job approves (`should_deploy=true`) - -## Release Workflow Integration - -The **release workflow** (`release.yml`) has been enhanced to support this pattern through the `DOCS_UPDATED` flag system. - -### DOCS_UPDATED Flag Generation - -During the version bump process, the release workflow: - -#### 1. Tracks Documentation Updates -Uses existing `DOCS_UPDATED` flag from bump step logic that already determines if documentation files need updating: - -```bash -# Version bump logic already sets DOCS_UPDATED flag -DOCS_UPDATED=false - -# Check if documentation files that reference versions need updating -if [[ -f "docs/contents/development/ci-cd/index.mdx" ]] || - [[ -f "docs/contents/document/installation.md" ]] || - [[ -f "docs/contents/document/README.md" ]]; then - DOCS_UPDATED=true -fi -``` - -#### 2. Updates Version References -Automatically updates documentation files that reference the package version: -- `docs/contents/development/ci-cd/index.mdx` -- `docs/contents/document/installation.md` -- `docs/contents/document/README.md` - -#### 3. Sets Output Flag -Outputs the `DOCS_UPDATED` flag for downstream workflows: - -```bash -# Output DOCS_UPDATED flag for documentation workflow trigger -echo "docs_updated=$DOCS_UPDATED" >> $GITHUB_OUTPUT -``` - -#### 4. Emits Artifact -Uploads the flag as an artifact for the documentation workflow: - -```yaml -- name: Upload docs update flag for downstream documentation workflow - uses: actions/upload-artifact@v4 - with: - name: release-docs-flag - path: docs_updated.txt - retention-days: 1 -``` - -## Documentation Deployment Process - -### Environment Setup - -The documentation deployment uses modern Node.js tooling: - -```yaml -- name: Setup Node.js - uses: actions/setup-node@v4 - with: - node-version: '22' - -- name: Setup pnpm - uses: pnpm/action-setup@v4 - with: - version: 8 - run_install: false - -- name: Get pnpm store directory - shell: bash - run: echo "STORE_PATH=$(pnpm store path --silent)" >> $GITHUB_ENV - -- name: Setup pnpm cache - uses: actions/cache@v4 - with: - path: ${{ env.STORE_PATH }} - key: ${{ runner.os }}-pnpm-store-${{ hashFiles('**/pnpm-lock.yaml') }} - restore-keys: | - ${{ runner.os }}-pnpm-store- -``` - -### Build Process - -**Docusaurus Build Steps**: - -1. **Install Dependencies**: - ```bash - pnpm install --frozen-lockfile - ``` - -2. **Build Static Documentation**: - ```bash - pnpm build - ``` - -3. **Generate Optimized Assets**: - - Static HTML, CSS, and JavaScript - - Optimized images and assets - - Search index generation - - PWA manifests - -### GitHub Pages Deployment - -**Deployment Steps**: - -1. **Configure GitHub Pages Environment**: - ```yaml - - name: Setup Pages - uses: actions/configure-pages@v5 - ``` - -2. **Upload Built Documentation**: - ```yaml - - name: Upload artifact - uses: actions/upload-pages-artifact@v3 - with: - path: ./build - ``` - -3. **Deploy to GitHub Pages**: - ```yaml - - name: Deploy to GitHub Pages - id: deployment - uses: actions/deploy-pages@v4 - ``` - -## Key Benefits - -βœ… **Reliable Triggering**: Documentation deploys automatically after releases that update docs -βœ… **No Infinite Loops**: Guard job prevents unnecessary deployments -βœ… **Efficient**: Only deploys when documentation actually changes -βœ… **Backward Compatible**: Direct push functionality remains unchanged -βœ… **Intelligent**: Uses existing business logic to determine if docs need updating -βœ… **Fast**: Leverages pnpm caching for quick builds -βœ… **Robust**: Multiple fallback mechanisms and error handling - -## Advanced Features - -### Multi-Path Trigger Monitoring - -The workflow monitors multiple file paths to ensure comprehensive documentation updates: - -```yaml -paths: - - "docs/**" # Core documentation - - "*.md" # Root markdown files - - "README*.md" # README variants - - ".github/workflows/documentation.yaml" # This workflow - - ".github/workflows/release.yml" # Release workflow - - ".github/workflows/release-*.yml" # Release variants - - ".github/workflows/rw_*.yaml" # Reusable workflows - - ".github/tag_and_release/**" # Release configuration -``` - -### Intelligent Artifact Management - -**Artifact Lifecycle**: -- **Creation**: Release workflow creates `release-docs-flag` artifact -- **Consumption**: Documentation workflow downloads and reads flag -- **Cleanup**: Artifacts automatically expire after 1 day -- **Error Handling**: Missing artifacts result in graceful skipping - -### Cross-Workflow Communication - -**Communication Pattern**: -```mermaid -sequenceDiagram - participant R as Release Workflow - participant A as GitHub Artifacts - participant D as Documentation Workflow - - R->>R: Determine DOCS_UPDATED - R->>A: Upload docs_updated.txt - R->>D: Trigger via workflow_run - D->>A: Download docs_updated.txt - D->>D: Evaluate flag - D->>D: Conditional deployment -``` - -## Troubleshooting - -### Common Issues and Solutions - -#### Documentation Not Deploying After Release - -**Symptoms**: Documentation doesn't update after a release that should have triggered it. - -**Diagnosis Steps**: -1. Check that the release workflow completed successfully -2. Verify that documentation files were actually updated (check `DOCS_UPDATED` flag in release logs) -3. Review the guard job output in the documentation workflow -4. Ensure the `release-docs-flag` artifact was created - -**Solutions**: -```bash -# Check release workflow status -gh run list --workflow=release.yml --limit=1 - -# Check documentation workflow status -gh run list --workflow=documentation.yaml --limit=1 - -# View specific run logs -gh run view --log -``` - -#### Guard Job Failing - -**Symptoms**: Documentation workflow guard job fails with artifact download errors. - -**Common Causes**: -- Release workflow didn't upload the `release-docs-flag` artifact -- Artifact download permissions incorrect -- Workflow run ID not accessible - -**Solutions**: -1. **Check Artifact Upload**: - ```yaml - # Verify this step exists in release workflow - - name: Upload docs update flag for downstream documentation workflow - uses: actions/upload-artifact@v4 - with: - name: release-docs-flag - path: docs_updated.txt - ``` - -2. **Verify Permissions**: - ```yaml - permissions: - contents: read - actions: read # Required for artifact download - ``` - -3. **Check Workflow Run ID**: - ```bash - # The workflow_run event should provide the correct run ID - echo "Release run ID: ${{ github.event.workflow_run.id }}" - ``` - -#### Deployment Timing Issues - -**Expected Behavior**: -- Workflow run triggers happen after the triggering workflow completes -- Documentation deployment occurs ~1-2 minutes after release completion -- Monitor both workflows to track the complete process - -**Debugging Timeline**: -1. Release workflow starts and completes -2. Documentation workflow triggered via `workflow_run` -3. Guard job evaluates `DOCS_UPDATED` flag -4. Deployment job runs if flag is `true` - -### Performance Optimization - -#### Build Speed Improvements - -**pnpm Caching Strategy**: -```yaml -- name: Setup pnpm cache - uses: actions/cache@v4 - with: - path: ${{ env.STORE_PATH }} - key: ${{ runner.os }}-pnpm-store-${{ hashFiles('**/pnpm-lock.yaml') }} - restore-keys: | - ${{ runner.os }}-pnpm-store- -``` - -**Benefits**: -- ~60% faster builds on cache hit -- Reduced bandwidth usage -- More reliable builds in case of registry issues - -#### Conditional Processing - -**Skip Logic**: -- Guard job prevents unnecessary builds -- Direct evaluation of `DOCS_UPDATED` flag -- Early exit for workflow_run events with no doc changes - -## Best Practices - -### For Contributors - -1. **Documentation Changes**: Direct documentation changes trigger immediate deployment -2. **Release Integration**: Version-related doc updates happen automatically during releases -3. **Testing**: Use staging branches to test documentation changes before merging -4. **Monitoring**: Check both release and documentation workflow statuses for complete picture - -### For Maintainers - -1. **Artifact Management**: Keep artifact retention short (1 day) to save storage -2. **Error Handling**: Monitor guard job failures and artifact issues -3. **Performance**: Review build times and optimize pnpm cache usage -4. **Security**: Ensure proper permissions for cross-workflow artifact access - -### Configuration Management - -**Release Integration Checklist**: -- βœ… Release workflow outputs `DOCS_UPDATED` flag -- βœ… Release workflow uploads `release-docs-flag` artifact -- βœ… Documentation workflow has `workflow_run` trigger -- βœ… Guard job correctly evaluates flag -- βœ… Deployment job has proper conditional logic - ---- - -πŸ”— **Related Documentation**: -- [Release System](./release-system.mdx) - Learn about the release workflow that triggers documentation updates -- [Continuous Integration](./continuous-integration.mdx) - Understanding the broader CI/CD context -- [Developer Guide](./developer-guide.mdx) - Advanced troubleshooting and configuration diff --git a/docs/contents/development/ci-cd/index.mdx b/docs/contents/development/ci-cd/index.mdx deleted file mode 100644 index 7749f8a..0000000 --- a/docs/contents/development/ci-cd/index.mdx +++ /dev/null @@ -1,96 +0,0 @@ ---- -title: CI/CD Workflows -sidebar_position: 6 ---- - -# CI/CD Workflows - -This section describes the Continuous Integration and Continuous Deployment (CI/CD) workflows used in the Python uv template project. - -## πŸš€ **Quick Navigation** - -Our CI/CD system is organized into focused, developer-friendly sections: - -### **πŸ“‹ [Continuous Integration](./continuous-integration.mdx)** - -[![CI](https://github.com/Chisanan232/Template-Python-UV-Project/actions/workflows/ci.yaml/badge.svg)](https://github.com/Chisanan232/Template-Python-UV-Project/actions/workflows/ci.yaml) -[![CI + E2E](https://github.com/Chisanan232/Template-Python-UV-Project/actions/workflows/ci_includes_e2e_test.yaml/badge.svg)](https://github.com/Chisanan232/Template-Python-UV-Project/actions/workflows/ci_includes_e2e_test.yaml) - -- **Matrix-based test coverage** across Python 3.12–3.14 and multiple OS targets -- **Quality gates** for linting, formatting, type checking, coverage -- **Reusable workflow design** so child projects can opt-in to shared automation -- **Samples for extending CI** with integration or E2E jobs - -### **πŸ”„ [Release System](./release-system.mdx)** - -[![Release Validation](https://github.com/Chisanan232/Template-Python-UV-Project/actions/workflows/release-validate.yml/badge.svg)](https://github.com/Chisanan232/Template-Python-UV-Project/actions/workflows/release-validate.yml) -[![Release](https://github.com/Chisanan232/Template-Python-UV-Project/actions/workflows/release.yml/badge.svg)](https://github.com/Chisanan232/Template-Python-UV-Project/actions/workflows/release.yml) -[![Release Staging](https://github.com/Chisanan232/Template-Python-UV-Project/actions/workflows/release-staging.yml/badge.svg)](https://github.com/Chisanan232/Template-Python-UV-Project/actions/workflows/release-staging.yml) - -- **Intent-driven configuration** via `.github/tag_and_release/intent.yaml` -- **Triple-target publishing**: Python package, container image, Docusaurus docs -- **Validation + staging** workflows to test releases before production -- **Supply-chain safeguards** (version bump enforcement, lockfile sync, summaries) - -### **πŸ“– [Documentation Deployment](./documentation-deployment.mdx)** - -[![Documentation](https://github.com/Chisanan232/Template-Python-UV-Project/actions/workflows/documentation.yaml/badge.svg)](https://github.com/Chisanan232/Template-Python-UV-Project/actions/workflows/documentation.yaml) - -- **workflow_run-based trigger** that reacts to release outputs and docs-only PRs -- **Safeguards** to prevent duplicate deployments and to validate build artifacts -- **DOCS_UPDATED flagging** for selective publishing -- **Guidance** for customizing deployment targets (gh-pages, GitHub Pages, custom domains) - -### **πŸ”§ [Reusable Workflows](./reusable-workflows.mdx)** -- **Step-by-step usage** of the reusable workflow catalog -- **Inputs/outputs tables** to help integrate from downstream projects -- **Patterns** for combining Python, Docker, and docs jobs without duplication - -### **βš™οΈ [Additional CI Workflows](./additional-ci-workflows.mdx)** - -[![Docker CI](https://github.com/Chisanan232/Template-Python-UV-Project/actions/workflows/docker-ci.yml/badge.svg)](https://github.com/Chisanan232/Template-Python-UV-Project/actions/workflows/docker-ci.yml) -[![DockerHub README CI](https://github.com/Chisanan232/Template-Python-UV-Project/actions/workflows/dockerhub-readme-ci.yml/badge.svg)](https://github.com/Chisanan232/Template-Python-UV-Project/actions/workflows/dockerhub-readme-ci.yml) -[![Docs Build Check](https://github.com/Chisanan232/Template-Python-UV-Project/actions/workflows/docs-build-check.yaml/badge.svg)](https://github.com/Chisanan232/Template-Python-UV-Project/actions/workflows/docs-build-check.yaml) - -- **Docker CI** – Standalone container validation without triggering full releases -- **DockerHub README** – Synchronizes `README_DOCKERHUB.md` with Docker Hub automatically -- **Docs build check** – Validates Docusaurus builds on PRs and non-main pushes -- **Docs auto-merge** – Streamlines docs-only PRs under guarded conditions - -### **πŸ› οΈ [Developer Guide](./developer-guide.mdx)** -- **Configuration and troubleshooting** -- **Best practices for contributors** -- **Common workflows and monitoring** -- **Additional specialized workflows** - ---- - -## 🎯 **CI/CD Overview** - -We use **GitHub Actions** to automate testing, code quality checks, and deployment processes. Our CI/CD pipelines help maintain code quality, ensure tests pass, and streamline the release process. - -**Monitor all workflows at:** [GitHub Actions Dashboard](https://github.com/Chisanan232/Template-Python-UV-Project/actions) - -### **System Highlights** - -βœ… **Comprehensive CI**: Multi-Python testing, code quality, coverage reporting -βœ… **Intelligent Releases**: Intent-based configuration with supply chain security -βœ… **Advanced Documentation**: workflow_run pattern with DOCS_UPDATED flag logic -βœ… **Reusable Architecture**: DRY workflows with standardized operations -βœ… **Developer-Friendly**: Extensive validation, staging, and troubleshooting guidance - ---- - -## 🎯 **Getting Started** - -**New to our CI/CD system?** Start with: - -1. **πŸ“‹ [Continuous Integration](./continuous-integration.mdx)** - Understand our testing and quality workflows -2. **πŸ”„ [Release System](./release-system.mdx)** - Learn about our release process and configuration -3. **πŸ› οΈ [Developer Guide](./developer-guide.mdx)** - Find practical examples and troubleshooting tips - -**Need specific information?** -- **Configuring releases:** β†’ [Release System](./release-system.mdx) -- **Documentation not deploying:** β†’ [Documentation Deployment](./documentation-deployment.mdx) -- **Understanding workflow patterns:** β†’ [Reusable Workflows](./reusable-workflows.mdx) -- **Troubleshooting issues:** β†’ [Developer Guide](./developer-guide.mdx) diff --git a/docs/contents/development/ci-cd/release-system.mdx b/docs/contents/development/ci-cd/release-system.mdx deleted file mode 100644 index e45dbfc..0000000 --- a/docs/contents/development/ci-cd/release-system.mdx +++ /dev/null @@ -1,130 +0,0 @@ ---- -title: Release System -sidebar_position: 3 ---- - -# Release System - -[![GitHub release](https://img.shields.io/github/v/release/Chisanan232/Template-Python-UV-Project?display_name=tag&color=24292e&logo=github)](https://github.com/Chisanan232/Template-Python-UV-Project/releases) - -The release workflows for this template are now maintained in the centralized repository `Chisanan232/GitHub-Action_Reusable_Workflows-Python`. This project consumes those reusable workflows for production, validation, and staging releases while keeping only minimal configuration locally. - -## Release workflows - -### Production release (`release.yml`) -[![Release](https://github.com/Chisanan232/Template-Python-UV-Project/actions/workflows/release.yml/badge.svg)](https://github.com/Chisanan232/Template-Python-UV-Project/actions/workflows/release.yml) -[![PyPI version](https://img.shields.io/pypi/v/test-python-uv-project-template?label=PyPI&color=306998&logo=pypi)](https://pypi.org/project/test-python-uv-project-template/) - -Publishes production artifacts (PyPI package, container images, docs) using the centralized `rw_release_complete.yaml` workflow logic. - -- **Purpose** – Ship the production-ready version of your project whenever you approve a release. -- **Effects** – Builds from locked dependencies, signs artifacts (if configured), pushes semantic tags, and updates changelog summaries. -- **Targets** – PyPI (wheel + sdist), Docker Hub/GHCR images, and the published Docusaurus docs site. - -```mermaid -flowchart LR - classDef config fill:#fef3c7,stroke:#d97706,color:#78350f; - classDef workflow fill:#4338ca,stroke:#1e1b4b,color:#fff; - classDef jobs fill:#e0f2fe,stroke:#0284c7,color:#0c4a6e; - classDef targets fill:#dcfce7,stroke:#15803d,color:#14532d,font-weight:bold; - - intent[intent.yaml
release configuration]:::config - trigger["release.yml
(local workflow)"]:::workflow - reusable["Reusable workflow
rw_release_complete.yaml"]:::workflow - jobs[Build β†’ Test β†’ Sign β†’ Publish]:::jobs - targets[(PyPI Β· Docker Hub/GHCR Β· Docs)]:::targets - - intent --> trigger --> reusable --> jobs --> targets -``` -- **Documentation** – See the reusable workflow guide for production releases: [rw_release_complete.yaml](https://chisanan232.github.io/GitHub-Action_Reusable_Workflows-Python/docs/next/workflows/release/rw_release_complete) (hosted in `Chisanan232/GitHub-Action_Reusable_Workflows-Python`). - -:::note Documentation -See the reusable workflow guide for production releases: [rw_release_complete.yaml](https://chisanan232.github.io/GitHub-Action_Reusable_Workflows-Python/docs/next/workflows/release/rw_release_complete) (hosted in `Chisanan232/GitHub-Action_Reusable_Workflows-Python`). -::: - -### Release staging (`release-staging.yml`) -[![Release Staging](https://github.com/Chisanan232/Template-Python-UV-Project/actions/workflows/release-staging.yml/badge.svg)](https://github.com/Chisanan232/Template-Python-UV-Project/actions/workflows/release-staging.yml) -[![TestPyPI version](https://img.shields.io/badge/dynamic/json?label=TestPyPI&color=ff6600&query=%24.info.version&url=https%3A%2F%2Ftest.pypi.org%2Fpypi%2Ftest-python-uv-project-template%2Fjson&logo=pypi)](https://test.pypi.org/project/test-python-uv-project-template/) - -Creates staging/TestPyPI packages, RC container images, and preview documentation to test releases before production. - -- **Purpose** – Provide a safe rehearsal of the full release pipeline with artifacts you can share internally. -- **Effects** – Publishes release-candidate packages, tags container images with `-rc`, and deploys docs to preview channels without touching production identifiers. -- **Targets** – TestPyPI, staging container registries (Docker Hub/GHCR), and preview docs buckets or branches. - -```mermaid -flowchart LR - classDef config fill:#fef3c7,stroke:#d97706,color:#78350f; - classDef workflow fill:#7c3aed,stroke:#4c1d95,color:#fff; - classDef jobs fill:#ede9fe,stroke:#6d28d9,color:#312e81; - classDef targets fill:#cffafe,stroke:#0e7490,color:#0f172a,font-weight:bold; - - intent[intent.yaml
staging overrides]:::config - trigger["release-staging.yml
(local workflow)"]:::workflow - reusable["Reusable workflow
rw_release_staging_complete.yaml"]:::workflow - jobs[Build β†’ Tag `-rc` β†’ Publish preview docs]:::jobs - targets[(TestPyPI Β· Staging registries Β· Preview docs)]:::targets - - intent --> trigger --> reusable --> jobs --> targets -``` -- **Documentation** – Reusable staging workflow reference: [rw_release_staging_complete.yaml](https://chisanan232.github.io/GitHub-Action_Reusable_Workflows-Python/docs/next/workflows/release/rw_release_staging_complete). - -:::note Documentation -Reusable staging workflow reference: [rw_release_staging_complete.yaml](https://chisanan232.github.io/GitHub-Action_Reusable_Workflows-Python/docs/next/workflows/release/rw_release_staging_complete). -::: - -### Release validation (`release-validate.yml`) -[![Release Validation](https://github.com/Chisanan232/Template-Python-UV-Project/actions/workflows/release-validate.yml/badge.svg)](https://github.com/Chisanan232/Template-Python-UV-Project/actions/workflows/release-validate.yml) - -Dry-runs the release pipeline for pull requests, verifying builds and security checks without publishing artifacts. - -- **Purpose** – Catch packaging, signing, or configuration issues before they reach staging or production. -- **Effects** – Executes the same jobs as a real release (build, test, SBOM, signing) but discards artifacts after validation. -- **Targets** – No registries are updated; results remain within the PR context and GitHub Actions artifact storage for review. - -```mermaid -flowchart LR - classDef config fill:#fef3c7,stroke:#d97706,color:#78350f; - classDef workflow fill:#0ea5e9,stroke:#1e3a8a,color:#fff; - classDef jobs fill:#dbeafe,stroke:#1d4ed8,color:#1e3a8a; - classDef targets fill:#fde68a,stroke:#c2410c,color:#7c2d12,font-weight:bold; - - intent[intent.yaml
validation mode]:::config - trigger["release-validate.yml
(local workflow)"]:::workflow - reusable["Reusable workflow
rw_release_validation_complete.yaml"]:::workflow - jobs[Build β†’ Test β†’ Security scans β†’ Summaries]:::jobs - targets[(Report only Β· Artifacts stored in run)]:::targets - - intent --> trigger --> reusable --> jobs --> targets -``` -- **Documentation** – Reusable validation workflow details: [rw_release_validation_complete.yaml](https://chisanan232.github.io/GitHub-Action_Reusable_Workflows-Python/docs/next/workflows/release/rw_release_validation_complete). - -:::note Documentation -Reusable validation workflow details: [rw_release_validation_complete.yaml](https://chisanan232.github.io/GitHub-Action_Reusable_Workflows-Python/docs/next/workflows/release/rw_release_validation_complete). -::: - -## Overview - -- **Centralized logic**: All release orchestration lives in the [reusable workflow repository](https://github.com/Chisanan232/GitHub-Action_Reusable_Workflows-Python). -- **Multi-target support**: Python packages, container images, and documentation publishing remain available through the shared workflows. -- **Configuration-driven**: Child projects configure releases via `intent.yaml`, delegating implementation details to the centralized workflows. -- **Release targets at a glance**: - - PyPI for production Python packages - - TestPyPI for staging/validation builds - - Docker Hub and GitHub Container Registry for container images - - Docusaurus documentation deployments - -:::note Learn more -For complete release architecture diagrams, configuration options, and usage guides, see the official documentation: - -- **Repository**: [Chisanan232/GitHub-Action_Reusable_Workflows-Python](https://github.com/Chisanan232/GitHub-Action_Reusable_Workflows-Python) -- **Documentation**: [Release System & Workflows Guide](https://chisanan232.github.io/GitHub-Action_Reusable_Workflows-Python/docs/next/introduction) - -These resources provide the authoritative, up-to-date reference for release operations after the migration to centralized workflows. -::: - -## Working in this template - -- Maintain `intent.yaml` to control release behavior for this project. -- Ensure workflow references point to the centralized repository (for example, `uses: Chisanan232/GitHub-Action_Reusable_Workflows-Python/.github/workflows/rw_release_complete.yaml@main`). -- Use the linked documentation for detailed steps, troubleshooting, and advanced configuration. diff --git a/docs/contents/development/ci-cd/reusable-workflows.mdx b/docs/contents/development/ci-cd/reusable-workflows.mdx deleted file mode 100644 index a2f1132..0000000 --- a/docs/contents/development/ci-cd/reusable-workflows.mdx +++ /dev/null @@ -1,27 +0,0 @@ ---- -title: Reusable Workflows -sidebar_position: 5 ---- - -# Reusable Workflows - -The reusable workflow implementations that power this template now live in the centralized repository `Chisanan232/GitHub-Action_Reusable_Workflows-Python`. This project simply references those shared workflows so every child project inherits the same battle-tested automation. - -## Overview - -- **Centralized maintenance**: Build, test, release, documentation, and packaging logic is defined once in the reusable workflow repository. -- **Lightweight template**: Local workflow files stay minimal by calling the centralized definitions with `uses: Chisanan232/GitHub-Action_Reusable_Workflows-Python/.github/workflows/.yaml@ref`. -- **Config driven**: Behavior is customized through `intent.yaml` and workflow inputs rather than editing workflow logic. - -:::note Learn more -For the complete list of reusable workflows, supported operations, inputs, outputs, and architecture diagrams, visit the centralized resources: - -- **Repository**: [Chisanan232/GitHub-Action_Reusable_Workflows-Python](https://github.com/Chisanan232/GitHub-Action_Reusable_Workflows-Python) -- **Documentation**: [Reusable Workflows Guide](https://chisanan232.github.io/GitHub-Action_Reusable_Workflows-Python/docs/next/introduction) -::: - -## Using them in this template - -- Reference the centralized workflows from `.github/workflows/*.yml` using an explicit ref such as `@main` or a released tag. -- Keep `intent.yaml` up to date; the centralized workflows read its values to decide which operations to run. -- Consult the linked documentation for advanced configuration, authentication details, and troubleshooting tips. diff --git a/docs/contents/development/ci-cd/type-checking-workflow.mdx b/docs/contents/development/ci-cd/type-checking-workflow.mdx deleted file mode 100644 index b153051..0000000 --- a/docs/contents/development/ci-cd/type-checking-workflow.mdx +++ /dev/null @@ -1,170 +0,0 @@ ---- -title: PEP 561 Type Distribution Workflow -sidebar_position: 7 ---- - -# PEP 561 Type Distribution Workflow - -[![PEP 561 Type Distribution](https://github.com/Chisanan232/Template-Python-UV-Project/actions/workflows/type-check.yml/badge.svg)](https://github.com/Chisanan232/Template-Python-UV-Project/actions/workflows/type-check.yml) - -The type-check.yml workflow ensures that the template package distributes its type information according to PEP 561 standards. - -**Triggers:** -- **Push to master**: When type distribution files are modified -- **Pull requests to master**: For PEP 561 compliance validation before merge -- **Manual dispatch**: On-demand validation via workflow dispatch - -**Purpose**: Validates PEP 561 compliance for type information distribution in Python packages. - -:::info MyPy Source Code Checking -**Note**: MyPy type checking of source code is handled by **pre-commit hooks** (configured in `.pre-commit-config.yaml`). This workflow focuses exclusively on **PEP 561 compliance** - ensuring type information is properly packaged and distributed. -::: - -## Overview - -This workflow validates type information distribution: - -- **PEP 561 Compliance** - Validates proper type information packaging and distribution -- **Type Imports** - Ensures type definitions are accessible and functional after installation -- **Distribution Verification** - Confirms type files are included in built packages - ---- - -## Workflow Jobs - -### 1. PEP 561 Compliance Verification (`verify-pep561-compliance`) - -Validates that the package correctly implements [PEP 561](https://peps.python.org/pep-0561/) standards for distributing type information with Python packages. - -**Purpose**: Ensures type checkers can automatically discover and use the package's type information after installation. - -**Validation Process:** - -**Step 1: Marker File Validation** -```bash -# Verify py.typed marker file exists -if [ ! -f "src/your_package/py.typed" ]; then - echo "Error: py.typed marker file not found!" - exit 1 -fi -py.typed marker file exists -``` - -**Step 2: Type Module Validation** -```bash -# Verify types.py module and exports -py.typed marker file exists -types.py module exists -types.py has __all__ export -``` - -**Step 3: Build Configuration Validation** -```bash -# Verify pyproject.toml includes type artifacts -pyproject.toml includes py.typed in artifacts -``` - -**Step 4: Distribution Verification** -```bash -# Build package and verify type files in distributions -uv build --sdist --wheel - -# Check source distribution -py.typed found in source distribution -types.py found in source distribution - -# Check wheel distribution -py.typed found in wheel distribution -types.py found in wheel distribution -``` - -**PEP Standards Validated:** -- [PEP 561](https://peps.python.org/pep-0561/) - Distributing and Packaging Type Information -- [PEP 484](https://peps.python.org/pep-0484/) - Type Hints -- [PEP 585](https://peps.python.org/pep-0585/) - Type Hinting Generics -- [PEP 544](https://peps.python.org/pep-0544/) - Protocols (Structural Subtyping) -- [PEP 695](https://peps.python.org/pep-0695/) - Type Parameter Syntax (Python 3.12+) - -### 2. Type Import Testing (`test-type-imports`) - -Validates that type definitions are correctly exported and accessible for use in application code. - -**Purpose**: Ensures the type system is functional and all type definitions can be imported and used as intended after package installation. - -**Test Categories:** - -**Module Import Validation** -```python -from your_package import types -Successfully imported types module -Available types: len(types.__all__) -``` - -**Type Accessibility Testing** - -The workflow validates that all major type categories are accessible: - -```python -# JSON type definitions -assert hasattr(types, 'JSONValue') -assert hasattr(types, 'JSONDict') -assert hasattr(types, 'JSONList') -assert hasattr(types, 'JSONPrimitive') -JSON types accessible - -# Protocol definitions (PEP 544) -assert hasattr(types, 'EventHandlerProtocol') -assert hasattr(types, 'QueueBackendProtocol') -Protocol types accessible - -# Type guard functions -assert hasattr(types, 'is_json_value') -assert hasattr(types, 'is_json_dict') -assert hasattr(types, 'is_json_list') -assert hasattr(types, 'is_json_primitive') -Type guards accessible -``` - -**Type Guard Functionality Testing** - -Validates runtime type validation functions work correctly: - -```python -# JSON type validation -assert types.is_json_value('{"key": "value"}') == True -assert types.is_json_value('{"key": "value"}') == True -assert types.is_json_value('{"key": "value"}') == True -JSON type guards work - -# Protocol type validation -assert types.is_event_handler_protocol(lambda x: x) == True -assert types.is_queue_backend_protocol(lambda x: x) == True -Protocol type guards work -``` - -### 3. PEP 561 Summary (`summary`) - -Aggregates results from all validation jobs and provides a comprehensive status report. - -**Purpose**: Provides a single source of truth for PEP 561 compliance status. - -**Dependencies**: Requires completion of both previous jobs (verify-pep561-compliance, test-type-imports) - -**Summary Report Format:** -```markdown -## PEP 561 Type Distribution Results - -Note: MyPy source code checking is handled by pre-commit hooks - -PASSED PEP 561 compliance -PASSED Type imports - -### PEP Standards Verified -- PEP 561: Distributing and Packaging Type Information -- PEP 484: Type Hints -- PEP 585: Type Hinting Generics -- PEP 544: Protocols (Structural Subtyping) -- PEP 695: Type Parameter Syntax (Python 3.12+) -``` - -**Failure Handling**: The workflow fails if any validation job does not succeed, ensuring type distribution compliance is maintained. diff --git a/docs/contents/development/sidebars.ts b/docs/contents/development/sidebars.ts index 9bfa090..e35f345 100644 --- a/docs/contents/development/sidebars.ts +++ b/docs/contents/development/sidebars.ts @@ -30,65 +30,6 @@ const sidebars: SidebarsConfig = { id: 'type-checking', label: 'πŸ” Type Checking with MyPy', }, - { - type: 'category', - label: 'πŸ—οΈ Architecture', - collapsed: false, - items: [ - { - type: 'doc', - id: 'architecture', - label: 'πŸ›οΈ Architecture Overview', - }, - ], - }, - { - type: 'category', - label: 'βš™οΈ CI/CD Workflows', - collapsed: false, - items: [ - { - type: 'doc', - id: 'ci-cd/index', - label: '🎯 CI/CD Overview', - }, - { - type: 'doc', - id: 'ci-cd/continuous-integration', - label: 'πŸ”„ Continuous Integration', - }, - { - type: 'doc', - id: 'ci-cd/release-system', - label: 'πŸš€ Release System', - }, - { - type: 'doc', - id: 'ci-cd/documentation-deployment', - label: 'πŸ“š Documentation Deployment', - }, - { - type: 'doc', - id: 'ci-cd/reusable-workflows', - label: '♻️ Reusable Workflows', - }, - { - type: 'doc', - id: 'ci-cd/additional-ci-workflows', - label: 'πŸ› οΈ Additional CI Workflows', - }, - { - type: 'doc', - id: 'ci-cd/type-checking-workflow', - label: 'πŸ” Type Checking Workflow', - }, - { - type: 'doc', - id: 'ci-cd/developer-guide', - label: 'πŸ‘¨β€πŸ’» Developer Guide', - }, - ], - }, ], }; From ada2814033c0b3cc382a62461414ddcfa219fc2c Mon Sep 17 00:00:00 2001 From: Chisanan232 Date: Sat, 25 Apr 2026 20:49:18 +0800 Subject: [PATCH 5/8] =?UTF-8?q?=F0=9F=93=9D=20docs:=20rewrite=20user=20doc?= =?UTF-8?q?s=20for=20Python=20SDK=20usage?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../document/api-references/index.mdx | 57 +++- docs/contents/document/changelog.mdx | 5 +- docs/contents/document/introduction.mdx | 147 +-------- .../document/quick-start/how-to-run.mdx | 289 ++---------------- docs/contents/document/quick-start/index.mdx | 23 +- .../document/quick-start/installation.mdx | 123 +------- .../document/quick-start/requirements.mdx | 94 +----- 7 files changed, 113 insertions(+), 625 deletions(-) diff --git a/docs/contents/document/api-references/index.mdx b/docs/contents/document/api-references/index.mdx index 202a79d..23a4d8b 100644 --- a/docs/contents/document/api-references/index.mdx +++ b/docs/contents/document/api-references/index.mdx @@ -6,4 +6,59 @@ sidebar_position: 3 # API References -This section provides detailed documentation for all the APIs available in this project. +## Top-level exports + +```python +from agent_assembly import ( + init_assembly, + AssemblyError, + AgentError, + PolicyError, + GatewayError, + ConfigurationError, +) +``` + +## Initialization + +### `init_assembly(gateway_url: str, agent_id: str, api_key: str | None = None) -> GatewayClient` + +Creates a configured `GatewayClient` instance. + +## Gateway client + +### `await GatewayClient.register_agent() -> dict` + +Sends a registration request to: + +- `POST /agents/{agent_id}/register` + +### `await GatewayClient.check_policy_compliance(action: str) -> dict` + +Sends a policy check request to: + +- `POST /agents/{agent_id}/policy/check` + +Request body: + +```json +{ "action": "tool.call" } +``` + +## Data models + +```python +from agent_assembly.models import AgentConfig, AgentState, PolicyEvaluation +``` + +## Exceptions + +```python +from agent_assembly.exceptions import ( + AssemblyError, + AgentError, + PolicyError, + GatewayError, + ConfigurationError, +) +``` diff --git a/docs/contents/document/changelog.mdx b/docs/contents/document/changelog.mdx index f290db8..683d0bc 100644 --- a/docs/contents/document/changelog.mdx +++ b/docs/contents/document/changelog.mdx @@ -6,4 +6,7 @@ sidebar_position: 5 # Change Log -This document provides a chronological record of all notable changes to this project. +Project history is tracked in GitHub pull requests and release notes. + +- Pull requests: +- Releases: diff --git a/docs/contents/document/introduction.mdx b/docs/contents/document/introduction.mdx index 13ceec3..159c538 100644 --- a/docs/contents/document/introduction.mdx +++ b/docs/contents/document/introduction.mdx @@ -4,144 +4,27 @@ title: Introduction sidebar_position: 1 --- -# Python UV Project Template +# Agent Assembly Python SDK -Welcome to the **Python UV Project Template** - a modern, production-ready template for Python projects that leverages the power of [uv](https://docs.astral.sh/uv/) package management and industry best practices. +The Agent Assembly Python SDK provides a lightweight client for connecting an agent to the governance gateway. -## What is This Template? +## Current Scope -This template provides a comprehensive foundation for Python projects, designed to eliminate the repetitive setup work that developers face when starting new projects. Instead of spending hours configuring tools, setting up CI/CD pipelines, and establishing project structure, you can focus immediately on building your application. +This SDK currently includes: -## The Problem It Solves +- SDK bootstrap via `init_assembly(...)` +- A gateway client (`GatewayClient`) for registration and policy checks +- Typed data models under `agent_assembly.models` +- A base exception hierarchy under `agent_assembly.exceptions` -Starting a new Python project often involves: +## Package Basics -- πŸ”§ **Setting up package management** (pip, poetry, or uv) -- πŸ“ **Creating proper project structure** with src layout -- πŸ§ͺ **Configuring testing frameworks** (pytest, coverage) -- βœ… **Setting up code quality tools** (black, pylint, mypy) -- πŸ”„ **Establishing CI/CD workflows** for automation -- πŸ“š **Creating documentation structure** -- 🐳 **Adding containerization support** -- ⚑ **Configuring pre-commit hooks** +- Package name: `agent-assembly` +- Python support: `>=3.12,<4.0` +- Source package: `agent_assembly/` -This template eliminates all of these setup tasks, providing you with a battle-tested foundation that follows Python community best practices. +## Repository -## Why Choose This Template? +- GitHub: -### ⚑ Lightning-Fast Package Management with uv - -Built around [uv](https://docs.astral.sh/uv/), the fastest Python package manager: - -- **10-100x faster** than pip and poetry for dependency resolution -- **Deterministic builds** with reliable lock files -- **Cross-platform compatibility** (Windows, macOS, Linux) -- **Drop-in replacement** for existing pip workflows - -### πŸ› οΈ Complete Development Toolkit - -Pre-configured with essential development tools: - -```bash -# Testing & Coverage -pytest, pytest-cov, pytest-asyncio, pytest-rerunfailures - -# Code Quality -black (formatting), pylint (linting), mypy (type checking) - -# Development Workflow -pre-commit hooks, GitHub Actions CI/CD -``` - -### πŸ“¦ Modern Project Structure - -Follows Python packaging best practices: - -``` -project/ -β”œβ”€β”€ src/ # Source code (src layout) -β”œβ”€β”€ test/ # Test suites -β”‚ β”œβ”€β”€ unit_test/ # Unit tests -β”‚ └── integration_test/ # Integration tests -β”œβ”€β”€ docs_with_docusarus/ # Documentation (Docusaurus) -β”œβ”€β”€ docs_with_mkdocs/ # Alternative docs (MkDocs) -β”œβ”€β”€ .github/workflows/ # CI/CD automation -β”œβ”€β”€ pyproject.toml # Project configuration -└── uv.lock # Dependency lock file -``` - -### πŸš€ Production-Ready Features - -- **Automated Testing**: Multi-Python version testing (3.12-3.14) -- **Code Quality Gates**: Automatic formatting, linting, and type checking -- **Security Scanning**: Built-in security checks and dependency updates -- **Release Automation**: Automated versioning and PyPI publishing -- **Documentation**: Both Docusaurus and MkDocs options -- **Containerization**: Docker support for deployment - -## Who Should Use This Template? - -### Perfect For: - -- **Python developers** starting new projects -- **Teams** wanting consistent project structure -- **Open source maintainers** needing professional project setup -- **Data scientists** building reproducible analysis projects -- **DevOps engineers** requiring containerized Python applications -- **Students** learning modern Python development practices - -### Project Types: - -- πŸ“¦ **Python libraries and packages** -- 🌐 **Web applications and APIs** -- πŸ€– **CLI tools and utilities** -- πŸ“Š **Data science and analysis projects** -- 🧠 **Machine learning projects** -- πŸ”§ **Internal tools and scripts** - -## Key Features at a Glance - -| Feature | Description | Benefit | -|---------|-------------|---------| -| **uv Package Management** | Fast, reliable dependency management | 10-100x faster installs | -| **Src Layout** | Modern Python project structure | Better import organization | -| **Multi-Python Support** | Python 3.12, 3.13, 3.14 | Future-proof compatibility | -| **Comprehensive Testing** | pytest with coverage and async support | Reliable, well-tested code | -| **Code Quality Tools** | black, pylint, mypy pre-configured | Consistent, high-quality code | -| **CI/CD Workflows** | GitHub Actions for automation | Automated testing and deployment | -| **Documentation** | Docusaurus and MkDocs options | Professional documentation | -| **Docker Support** | Ready-to-use containerization | Easy deployment and distribution | -| **Pre-commit Hooks** | Automated quality checks | Catch issues before commit | - -## Philosophy - -This template embodies several key principles: - -1. **Developer Experience First**: Minimize setup friction, maximize productivity -2. **Industry Standards**: Follow Python community best practices and PEPs -3. **Modern Tooling**: Leverage the latest, fastest tools (uv, GitHub Actions) -4. **Flexibility**: Provide options without being opinionated about your specific use case -5. **Maintainability**: Structure code for long-term success -6. **Quality by Default**: Built-in quality gates and automation - -## Getting Started - -Ready to create your first project? Head over to our [Quick Start Guide](./quick-start/index.mdx) for step-by-step instructions on: - -1. **Creating a new project** from this template -2. **Installing dependencies** with uv -3. **Customizing the template** for your needs -4. **Setting up your development workflow** - -## Community and Support - -This template is actively maintained and continuously improved based on: - -- **Community feedback** and contributions -- **Industry best practices** evolution -- **Python ecosystem** developments -- **Security updates** and dependency management - ---- - -*Ready to build something amazing? Let's get started with modern Python development! 🐍✨* +Use [Quick Start](./quick-start/index.mdx) to get running locally. diff --git a/docs/contents/document/quick-start/how-to-run.mdx b/docs/contents/document/quick-start/how-to-run.mdx index f63652b..9c8ef67 100644 --- a/docs/contents/document/quick-start/how-to-run.mdx +++ b/docs/contents/document/quick-start/how-to-run.mdx @@ -4,288 +4,37 @@ title: How to Run sidebar_position: 3 --- -```mdx-code-block -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -``` - -# Customizing Your New Project - -This guide explains how to customize and configure your new Python project after creating it from the template. - -## Step 1: Update Project Metadata - -After creating your project from the template, customize the `pyproject.toml` file with your project details: - -```toml title="pyproject.toml" -[project] -name = "your-project-name" # ← Update this -version = "0.1.0" # ← Set initial version -description = "Your project description" # ← Update this -authors = [{ name = "Your Name", email = "your.email@example.com" }] # ← Update this -requires-python = ">=3.12,<4.0" -readme = "README.md" -license = { file = "LICENSE" } -keywords = ["your", "project", "keywords"] # ← Add relevant keywords -``` - -## Step 2: Set Up Development Environment - -### Install Dependencies and Activate Environment - -```bash -# Install all dependencies (including dev tools) -uv sync - -# Activate the virtual environment (optional, uv run handles this automatically) -source .venv/bin/activate # macOS/Linux -# or -.venv\Scripts\activate # Windows -``` +# How to Run -### Set Up Pre-commit Hooks +## Minimal SDK usage -```bash -# Install pre-commit hooks for code quality -uv run pre-commit install - -# Test pre-commit setup -uv run pre-commit run --all-files -``` - -## Step 3: Customize Project Structure - -### Update README.md - -Replace the template placeholders in `README.md`: - -```markdown title="README.md" -# Your Project Name - -## Overview -Brief description of what your project does - -## Installation -pip install your-package-name -# or -uv add your-package-name - -## Quick Start ```python -from your_project import main_function +import asyncio -result = main_function() -print(result) -``` +from agent_assembly import init_assembly -Replace `` placeholders with your actual project name. -### Add Your Source Code +async def main() -> None: + client = init_assembly( + gateway_url="http://localhost:8080", + agent_id="my-agent-001", + api_key="optional-api-key", + ) - - + try: + registration = await client.register_agent() + policy_result = await client.check_policy_compliance("tool.call") + print(registration) + print(policy_result) + finally: + client.close() -```bash -# Create your main package -mkdir src/your_project_name -touch src/your_project_name/__init__.py -touch src/your_project_name/main.py -# Example main.py content -echo 'def hello_world(): - return "Hello from your project!" - -if __name__ == "__main__": - print(hello_world())' > src/your_project_name/main.py -``` - - - - -```bash -# Create a single module -touch src/your_module.py - -# Example module content -echo 'def main(): - """Main function of your project.""" - print("Welcome to your new project!") - -if __name__ == "__main__": - main()' > src/your_module.py +asyncio.run(main()) ``` - - - -## Step 4: Development Workflow - -### Running Tests +## Run tests ```bash -# Run all tests uv run pytest - -# Run tests with coverage -uv run pytest --cov=src --cov-report=html - -# Run specific test file -uv run pytest test/unit_test/test_example.py -``` - -### Code Quality Checks - -```bash -# Format code with black -uv run black src/ test/ - -# Lint code with pylint -uv run pylint src/ - -# Type checking with mypy -uv run mypy src/ - -# Run all pre-commit hooks -uv run pre-commit run --all-files -``` - -### Adding Dependencies - - - - -```bash -# Add production dependencies -uv add requests pandas numpy - -# Add with version constraints -uv add "fastapi>=0.100.0,<1.0.0" ``` - - - - -```bash -# Add development dependencies -uv add --dev black pylint mypy - -# Add to specific dependency group -uv add --group test pytest-mock -``` - - - - -## Step 5: Configure CI/CD - -The template includes GitHub Actions workflows in `.github/workflows/`: - -### Update GitHub Secrets (if needed) - -For advanced workflows, you may need to configure repository secrets: - -1. Go to your GitHub repository β†’ Settings β†’ Secrets and variables β†’ Actions -2. Add any required secrets (e.g., PyPI tokens, deployment keys) - -### Customize Workflows - -Edit `.github/workflows/ci.yaml` to match your project needs: - -```yaml title=".github/workflows/ci.yaml" -name: CI -on: [push, pull_request] - -jobs: - test: - runs-on: ubuntu-latest - strategy: - matrix: - python-version: ["3.12", "3.13"] # Customize Python versions - - steps: - - uses: actions/checkout@v4 - - name: Set up uv - uses: ./.github/actions/setup-python-uv - with: - python-version: ${{ matrix.python-version }} - - # Your custom test steps here -``` - -## Step 6: Documentation Setup - -### Docusaurus Documentation (Optional) - -```bash -# Navigate to documentation directory -cd docs_with_docusarus - -# Install documentation dependencies -npm install - -# Start development server -npm start - -# Build static documentation -npm run build -``` - -### MkDocs Documentation (Alternative) - -```bash -# Navigate to MkDocs directory -cd docs_with_mkdocs - -# Install MkDocs dependencies -uv run pip install -r requirements.txt - -# Start development server -uv run mkdocs serve - -# Build documentation -uv run mkdocs build -``` - -## Step 7: Final Setup - -### Initialize Git Repository - -```bash -# If you used Method 2 (manual setup) from installation -git add . -git commit -m "Initial commit from Python UV template" - -# Connect to remote repository -git remote add origin https://github.com/YOUR-USERNAME/YOUR-PROJECT.git -git push -u origin main -``` - -### Clean Up Template References - -1. Remove or update template-specific files you don't need -2. Update documentation to reflect your project -3. Customize GitHub issue templates in `.github/ISSUE_TEMPLATE/` - -## Running Your Project - -After customization, test that everything works: - -```bash -# Run your main module -uv run python -m src.your_project_name - -# Or run directly -uv run python src/your_project_name/main.py - -# Install in editable mode for development -uv sync --dev -``` - -πŸŽ‰ **Congratulations!** Your Python project with uv management is now ready for development! - -## Next Steps - -- Set up your IDE/editor with Python and uv support -- Configure additional development tools as needed -- Start building your amazing Python project! -- Consider setting up automated releases using the included GitHub Actions diff --git a/docs/contents/document/quick-start/index.mdx b/docs/contents/document/quick-start/index.mdx index 3f78bfa..9e62e18 100644 --- a/docs/contents/document/quick-start/index.mdx +++ b/docs/contents/document/quick-start/index.mdx @@ -4,23 +4,12 @@ title: Quick Start sidebar_position: 2 --- -# Getting Started with Python UV Project Template +# Quick Start -This template provides a modern Python project structure with **uv** package management, comprehensive development tooling, and automated workflows. It's designed to help you quickly bootstrap new Python projects with industry best practices. +Use this guide to install the SDK and run a minimal gateway interaction flow. -## What's Included +## Guides -βœ… **Modern Package Management**: Pre-configured with [uv](https://docs.astral.sh/uv/) for fast, reliable dependency management -βœ… **Development Tools**: Testing (pytest), linting (pylint), formatting (black), type checking (mypy) -βœ… **CI/CD Workflows**: GitHub Actions for testing, code quality, and automated releases -βœ… **Documentation**: Ready-to-use documentation setup with Docusaurus and MkDocs -βœ… **Docker Support**: Containerization setup for easy deployment -βœ… **Code Quality**: Pre-commit hooks and comprehensive configuration files - -## Quick Setup Guide - -Choose one of the sections below to get started: - -- [Requirements](./requirements.mdx) - System and software prerequisites for using this template -- [Installation](./installation.mdx) - Step-by-step guide to create a new project from this template -- [How to Run](./how-to-run.mdx) - Instructions for setting up and customizing your new project +- [Requirements](./requirements.mdx) +- [Installation](./installation.mdx) +- [How to Run](./how-to-run.mdx) diff --git a/docs/contents/document/quick-start/installation.mdx b/docs/contents/document/quick-start/installation.mdx index ac5a0e2..0bfe393 100644 --- a/docs/contents/document/quick-start/installation.mdx +++ b/docs/contents/document/quick-start/installation.mdx @@ -4,129 +4,18 @@ title: Installation sidebar_position: 2 --- -```mdx-code-block -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -``` - -# Creating a New Project from Template - -This guide provides step-by-step instructions for creating a new Python project using this template. - -## Method 1: Using GitHub Template (Recommended) - -### Step 1: Create Repository from Template - -1. Navigate to the [template repository](https://github.com/Chisanan232/Template-Python-UV-Project) -2. Click the **"Use this template"** button (green button) -3. Select **"Create a new repository"** -4. Configure your new repository: - - **Repository name**: Enter your project name - - **Description**: Brief description of your project - - **Visibility**: Choose Public or Private - - **Include all branches**: Leave unchecked (recommended) - -### Step 2: Clone Your New Repository - -```bash -git clone https://github.com/YOUR-USERNAME/YOUR-PROJECT-NAME.git -cd YOUR-PROJECT-NAME -``` - -## Method 2: Manual Setup +# Installation -### Step 1: Download or Clone Template - - - +## Install from source repository ```bash -git clone https://github.com/Chisanan232/Template-Python-UV-Project.git my-new-project -cd my-new-project -rm -rf .git # Remove template's git history -git init # Initialize new git repository -``` - - - - -1. Go to the [template repository](https://github.com/Chisanan232/Template-Python-UV-Project) -2. Click **"Code"** β†’ **"Download ZIP"** -3. Extract the ZIP file to your desired location -4. Rename the folder to your project name - - - - -### Step 2: Install uv Package Manager - - - - -```bash -# Using Homebrew -brew install uv - -# Or using curl -curl -LsSf https://astral.sh/uv/install.sh | sh -``` - - - - -```bash -# Using curl -curl -LsSf https://astral.sh/uv/install.sh | sh - -# Or using pip -pip install uv -``` - - - - -```powershell -# Using PowerShell -powershell -c "irm https://astral.sh/uv/install.ps1 | iex" - -# Or using pip -pip install uv -``` - - - - -### Step 3: Initialize Project Dependencies - -```bash -# Install all dependencies including dev tools +git clone https://github.com/AI-agent-assembly/python-sdk.git +cd python-sdk uv sync - -# Or install only production dependencies -uv sync --no-dev ``` -## Next Steps - -After completing the installation: - -1. **Customize the project** - See [How to Run](./how-to-run.mdx) for customization steps -2. **Update project metadata** - Modify `pyproject.toml` with your project details -3. **Set up development environment** - Configure pre-commit hooks and IDE settings - -## Verification - -Verify your installation by running: +## Alternative with pip ```bash -# Check uv installation -uv --version - -# Check Python environment -uv run python --version - -# Run tests to ensure everything works -uv run pytest +pip install git+https://github.com/AI-agent-assembly/python-sdk.git ``` - -If all commands execute successfully, your project template is ready for development! πŸŽ‰ diff --git a/docs/contents/document/quick-start/requirements.mdx b/docs/contents/document/quick-start/requirements.mdx index 6091181..331b797 100644 --- a/docs/contents/document/quick-start/requirements.mdx +++ b/docs/contents/document/quick-start/requirements.mdx @@ -6,94 +6,14 @@ sidebar_position: 1 # Requirements -Before using this Python project template, ensure your development environment meets the following requirements: +## Runtime -## System Requirements +- Python `>=3.12,<4.0` +- Network access to your Agent Assembly gateway endpoint -- **Operating System**: Linux, macOS, or Windows -- **Memory**: Minimum 512MB RAM (1GB+ recommended for development) -- **Disk Space**: Minimum 500MB for full template with dependencies -- **Internet Connection**: Required for downloading dependencies and packages +## Local Development -## Core Prerequisites +- `uv` (recommended) +- Git -### Python Version - -- **Python**: Version 3.12 or higher (up to 3.14 supported) -- **Recommended**: Python 3.13 for optimal compatibility - -:::tip Python Installation -If you don't have Python installed: -- **macOS**: Use `brew install python` or download from [python.org](https://www.python.org/) -- **Linux**: Use your package manager (e.g., `apt install python3.13`) -- **Windows**: Download from [python.org](https://www.python.org/) or use `winget install Python.Python.3.13` -::: - -### Package Manager: uv (Required) - -This template is specifically designed for **[uv]** - a fast, modern Python package manager written in Rust. - -**Why uv?** -- ⚑ **10-100x faster** than pip/poetry for dependency resolution -- πŸ”’ **Deterministic builds** with lockfile support -- πŸ› οΈ **All-in-one tool** for project management, virtual environments, and Python installation -- πŸ“¦ **Drop-in replacement** for pip with better dependency resolution - -[uv]: https://docs.astral.sh/uv/ - -### Version Control - -- **Git**: Version 2.20 or higher -- **GitHub Account**: For template creation and repository management (recommended) - -## Development Tools (Included in Template) - -These tools are automatically configured when you use this template: - -- **Testing**: pytest, pytest-cov, pytest-asyncio, pytest-rerunfailures -- **Code Quality**: pylint, mypy, black formatting -- **Pre-commit Hooks**: Automated code quality checks -- **CI/CD**: GitHub Actions workflows - -## Optional Requirements - -### For Documentation Development - -- **Node.js**: Version 16+ (for Docusaurus documentation) -- **npm/yarn**: For managing documentation dependencies - -### For Containerized Deployment - -- **Docker**: Version 20.10.0 or later -- **Docker Compose**: Version 2.0+ (for multi-service applications) - -### For Advanced Development - -- **IDE Extensions**: Python, pylint, mypy support (VS Code, PyCharm recommended) -- **Terminal**: Modern terminal with color support for better uv output - -## Compatibility Matrix - -| Component | Minimum Version | Recommended | Notes | -|-----------|----------------|-------------|-------| -| Python | 3.12 | 3.13 | Template supports 3.12-3.14 | -| uv | 0.1.0 | Latest | Critical for dependency management | -| Git | 2.20 | 2.40+ | Required for version control | -| Docker | 20.10 | Latest | Optional, for containerization | - -## Verification Commands - -After installing prerequisites, verify your setup: - -```bash -# Check Python version -python --version - -# Check uv installation -uv --version - -# Check Git -git --version -``` - -All commands should return version numbers without errors to proceed with template setup. +Install `uv` from: From 60b568a310dfc5d275b04ade0899720619288af0 Mon Sep 17 00:00:00 2001 From: Chisanan232 Date: Sat, 25 Apr 2026 20:49:44 +0800 Subject: [PATCH 6/8] =?UTF-8?q?=F0=9F=93=9D=20docs:=20rewrite=20developmen?= =?UTF-8?q?t=20guides=20for=20this=20SDK=20repo?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/contents/development/coding-style.mdx | 359 +------------------- docs/contents/development/index.mdx | 24 +- docs/contents/development/requirements.mdx | 136 +------- docs/contents/development/type-checking.mdx | 94 +---- docs/contents/development/workflow.mdx | 217 +----------- 5 files changed, 58 insertions(+), 772 deletions(-) diff --git a/docs/contents/development/coding-style.mdx b/docs/contents/development/coding-style.mdx index 6886aaa..45c4a15 100644 --- a/docs/contents/development/coding-style.mdx +++ b/docs/contents/development/coding-style.mdx @@ -6,356 +6,25 @@ sidebar_position: 4 # Coding Styles and Rules -To maintain consistency and quality across the codebase, we follow these coding standards and rules. All contributors are expected to adhere to these guidelines. +## Python style -[![pre-commit enabled](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white)](https://pre-commit.com/) -[![Black code style](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black) -[![isort imports](https://img.shields.io/badge/imports-isort-ef8336?logo=python&logoColor=white)](https://pycqa.github.io/isort/) -[![Flake8 linting](https://img.shields.io/badge/lint-flake8-4B8BBE)](https://flake8.pycqa.org/) -[![MyPy type checking](https://img.shields.io/badge/types-mypy-2A6DB5)](https://mypy.readthedocs.io/en/stable/) -[![Pylint linting](https://img.shields.io/badge/lint-pylint-ffcc00)](https://pylint.readthedocs.io/en/latest/) +- Follow PEP 8 +- Prefer explicit typing in public interfaces +- Keep functions small and readable -## Python Code Style +## Linting and formatting -### PEP 8 +This repository uses: -We follow [PEP 8](https://www.python.org/dev/peps/pep-0008/) for Python code style with a few modifications: +- Ruff (`ruff.toml`) +- PyLint (`.pylintrc`) +- MyPy (`mypy.ini`) +- pre-commit (`.pre-commit-config.yaml`) -- Maximum line length: 100 characters -- Use 4 spaces for indentation (never tabs) -- Use snake_case for functions, methods, and variables -- Use CamelCase for classes -- Use UPPER_CASE for constants - -### Type Annotations - -We use type annotations throughout the codebase to improve code readability and enable static type checking: - -```python -def get_task(task_id: str) -> SampleDataModel: - """ - Retrieve a task by its ID. - - Args: - task_id: The ID of the task to retrieve - - Returns: - ClickUpTask: The retrieved task object - - Raises: - TaskNotFoundError: If the task doesn't exist - """ - # Implementation -``` - -Type annotations are checked using MyPy during CI/CD. - -### Python Typing Standards - -We adhere to modern Python typing standards as defined in various PEPs: - -#### PEP 484 - Type Hints - -[PEP 484](https://www.python.org/dev/peps/pep-0484/) introduced the typing module and the core syntax for type annotations: - -```python -from typing import Dict, List, Optional, Union - -# Use Optional for values that may be None -def get_user(user_id: Optional[str] = None) -> Optional[User]: - pass - -# Use Union for values that could be multiple types -def process_input(data: Union[str, bytes]) -> Dict[str, int]: - pass -``` - -#### PEP 585 - Type Hinting Generics in Standard Collections - -[PEP 585](https://www.python.org/dev/peps/pep-0585/) allows using built-in collection types directly for annotations (Python 3.9+): - -```python -# Python 3.9+ preferred style -def process_items(items: list[str]) -> dict[str, int]: - return {item: len(item) for item in items} - -# Instead of the older style with the typing module -# def process_items(items: List[str]) -> Dict[str, int]: -``` - -When supporting Python versions before 3.9, use the typing module equivalents. - -#### PEP 646 - Variadic Generics - -[PEP 646](https://peps.python.org/pep-0646/) introduced TypeVarTuple for variadic generics (Python 3.11+): - -```python -from typing import TypeVar, TypeVarTuple, Unpack - -T = TypeVar('T') -Ts = TypeVarTuple('Ts') - -def process_batch(batch: tuple[T, *Unpack[Ts]]) -> list[T]: - first, *rest = batch - return [first] -``` - -Use this for handling arbitrary homogeneous sequences when needed in higher-order functions. - -#### PEP 695 - Type Parameter Syntax - -[PEP 695](https://peps.python.org/pep-0695/) introduced simplified syntax for generic type definitions (Python 3.12+): - -```python -# Python 3.12+ simplified generic syntax -def identity[T](x: T) -> T: - return x - -# Instead of the more verbose -# T = TypeVar('T') -# def identity(x: T) -> T: -# return x -``` - -For backward compatibility, use the TypeVar approach when targeting Python versions before 3.12. - -### Duck Typing and Protocols - -Following Python's "duck typing" philosophy while maintaining type safety, we use Protocols (PEP 544) instead of requiring specific classes: - -```python -from typing import Protocol, runtime_checkable - -@runtime_checkable -class Clickable(Protocol): - def click(self) -> None: - ... - -def perform_click(item: Clickable) -> None: - item.click() # Works with any object that has a click() method -``` - -#### Protocol Best Practices - -1. **Use structural subtyping**: Focus on what objects do (methods/attributes they provide) rather than what they are (their class hierarchy) - -2. **Define minimal interfaces**: Only include methods and attributes that are actually needed - -3. **Use `@runtime_checkable` sparingly**: Only when you need `isinstance()` checks, which should be rare - -4. **Combine with generics when appropriate**: - -```python -from typing import TypeVar, Protocol, Generic - -T = TypeVar('T') - -class Repository(Protocol, Generic[T]): - def get(self, id: str) -> T: - ... - def save(self, item: T) -> None: - ... -``` - -5. **Use TypedDict for dictionary interfaces**: - -```python -from typing import TypedDict - -class TaskData(TypedDict): - id: str - name: str - status: str - priority: int -``` - -### Type Narrowing - -Use type guards and assertion functions for type narrowing: - -```python -from typing import TypeGuard, assert_type - -def is_string_list(val: list[object]) -> TypeGuard[list[str]]: - return all(isinstance(x, str) for x in val) - -def process_strings(items: list[object]) -> None: - if is_string_list(items): - # items is now known to be list[str] - for item in items: - assert_type(item, str) - print(item.upper()) -``` - -### Docstrings - -We use Google-style docstrings: - -```python -def function_name(param1: type, param2: type) -> return_type: - """Short description of the function. - - Longer description if necessary, explaining details. - - Args: - param1: Description of param1 - param2: Description of param2 - - Returns: - Description of the return value - - Raises: - ExceptionType: When and why this exception is raised - """ - # Implementation -``` - -## Code Organization - -### Imports - -Organize imports in the following order, with a blank line between each group: - -1. Standard library imports -2. Third-party library imports -3. Local application imports - -```python -import os -import sys -from typing import Dict, List, Optional - -import httpx -from pydantic import BaseModel, Field - -from your_repo.models import SampleDataModel -from your_repo.utils import logger -``` - -### File and Directory Structure - -- One class per file where appropriate -- Group related functionality into modules -- Keep files focused on a single responsibility - -## Code Quality Tools - -We use several tools to ensure code quality: - -### Pre-commit Hooks - -We use pre-commit hooks to automatically check code quality before committing. Install them with: +## Commands ```bash -pre-commit install -``` - -Our pre-commit hooks include: - -- Black for code formatting -- isort for import sorting -- flake8 for linting -- mypy for type checking - -### PyLint Configuration - -The project uses PyLint for comprehensive code analysis with configuration in [.pylintrc](https://github.com/Chisanan232/Template-Python-UV-Project/blob/master/.pylintrc). Our PyLint rules are based on the [Google Python Style Guide](https://google.github.io/styleguide/pyguide.html). - -Key PyLint settings include: - -```ini -[MASTER] -ignore=CVS -ignore-patterns= -persistent=yes -load-plugins= -jobs=0 - -[MESSAGES CONTROL] -# Disable specific PyLint checks that conflict with our style choices -disable=raw-checker-failed, - bad-inline-option, - locally-disabled, - file-ignored, - suppressed-message, - useless-suppression, - deprecated-pragma, - use-symbolic-message-instead +uv run ruff check . +uv run mypy agent_assembly +uv run pre-commit run --all-files ``` - -Run PyLint on your code with: - -```bash -pylint your_module_or_file.py -``` - -### MyPy Configuration - -MyPy type checking is configured in [mypy.ini](https://github.com/Chisanan232/Template-Python-UV-Project/blob/master/mypy.ini), enforcing strict typing rules: - -```ini -[mypy] -python_version = 3.13 -warn_return_any = True -warn_unused_configs = True -disallow_untyped_defs = True -disallow_incomplete_defs = True -check_untyped_defs = True -disallow_untyped_decorators = True -no_implicit_optional = True -strict_optional = True - -# Exclude scripts directory from type checking -[mypy-scripts.*] -ignore_errors = True -``` - -Run MyPy to check your code with: - -```bash -mypy your_module_or_package -``` - -### Black Configuration - -Black is configured in `pyproject.toml`: - -```toml -[tool.black] -line-length = 100 -target-version = ['py39'] -``` - -### Flake8 Configuration - -Flake8 is configured in `.flake8`: - -```ini -[flake8] -max-line-length = 100 -exclude = .git,__pycache__,build,dist -``` - -### Testing - -- All code should have unit tests -- Aim for high test coverage, especially for critical paths -- Tests should be fast and independent of each other - -## Pull Request Guidelines - -- Keep changes focused and limited in scope -- Include tests for new functionality -- Update documentation as needed -- Run pre-commit hooks before submitting -- Address all CI/CD failures - -## Best Practices - -- Write self-documenting code with descriptive variable and function names -- Follow the DRY (Don't Repeat Yourself) principle -- Keep functions small and focused on a single responsibility -- Use exceptions for error handling, not return codes -- Use type annotations consistently -- Write comprehensive tests -- Document all public APIs diff --git a/docs/contents/development/index.mdx b/docs/contents/development/index.mdx index 785b597..51b45ae 100644 --- a/docs/contents/development/index.mdx +++ b/docs/contents/development/index.mdx @@ -6,23 +6,11 @@ sidebar_position: 1 # Development Guide -Welcome to the Python uv project template development guide! This section provides comprehensive information for developers who want to understand, modify, or contribute to the project. +This section documents the contributor workflow for the Python SDK repository. -## Getting Started +## Main Areas -If you're new to the project, we recommend starting with these sections: - -- [Requirements](./requirements.mdx) - Development environment prerequisites -- [Development Workflow](./workflow.mdx) - How to set up and contribute to the project -- [Coding Style and Rules](./coding-style.mdx) - Coding conventions used in the project - -## Going Deeper - -Once you're familiar with the basics, you can explore: - -- [Software Architecture](./architecture.mdx) - Overview of the project architecture -- [CI/CD Workflows](./ci-cd/index.mdx) - Continuous Integration and Deployment processes - -## Contributing - -We welcome contributions! Before submitting code, please make sure you've read the [Contributing Guide](/docs/next/contribute) as well as the detailed development sections in this guide. +- [Requirements](./requirements.mdx) +- [Development Workflow](./workflow.mdx) +- [Coding Styles and Rules](./coding-style.mdx) +- [Type Checking with MyPy](./type-checking.mdx) diff --git a/docs/contents/development/requirements.mdx b/docs/contents/development/requirements.mdx index ffac6a7..302707d 100644 --- a/docs/contents/development/requirements.mdx +++ b/docs/contents/development/requirements.mdx @@ -4,133 +4,23 @@ title: Requirements sidebar_position: 2 --- -```mdx-code-block -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -``` - # Development Requirements -Before you begin contributing to Python uv project template, ensure your development environment meets these requirements. - -## Software Prerequisites - -### Required Software - -- **Python**: Python 3.13 or higher -- **Git**: Latest stable version -- **pip**, **poetry** or **uv**: Latest version -- **virtualenv** or **pyenv**: For creating isolated Python environments - -### Recommended Development Tools - -- **Visual Studio Code**, **PyCharm**, or other IDE with Python support -- **pre-commit**: For running pre-commit hooks -- **Docker**: For containerized testing and deployment - -## Python Dependencies - -The project has several dependencies that will be installed automatically when you set up the development environment: - -- **FastAPI**: Web framework for API endpoints -- **Pydantic**: Data validation and settings management -- **httpx**: HTTP client for async requests -- **pytest**: Testing framework -- **python-dotenv**: Environment variable management -- **uvicorn**: ASGI server for running the application - -## Development Environment Setup - -1. **Clone the repository**: - ```bash - git clone https://github.com//.git - cd your_repo - ``` +## Required -2. **Create a virtual environment**: - - - - ```bash - python -m venv venv - source venv/bin/activate # On Windows: venv\Scripts\activate - ``` +- Python `>=3.12,<4.0` +- `uv` +- Git - - - ```bash - conda create -n your_repo python=3.13 - conda activate your_repo - ``` +## Setup - - - ```bash - poetry shell - ``` - - - - ```bash - uv venv - source .venv/bin/activate - ``` - - - - -3. **Install development dependencies**: - - - - ```bash - pip install -e ".[dev]" - ``` - - - - ```bash - poetry install --with=dev - ``` - - - - ```bash - uv pip install . - ``` - - - - -4. **Set up pre-commit hooks**: - - - - ```bash - pre-commit install - ``` - - - - ```bash - poetry run pre-commit install - ``` - - - - ```bash - uv run pre-commit install - ``` - - - - -5. **Create a `.env` file for local development**: - ```bash - cp .env.example .env - # Edit .env with your service API token - ``` +```bash +git clone https://github.com/AI-agent-assembly/python-sdk.git +cd python-sdk +uv sync +``` -## Next Steps +## Optional -Once your development environment is set up, refer to the [Development Workflow](./workflow.mdx) documentation for the next steps. +- `pre-commit` hooks +- Node.js and pnpm only if you are editing `docs/` diff --git a/docs/contents/development/type-checking.mdx b/docs/contents/development/type-checking.mdx index 49e2d77..daaebab 100644 --- a/docs/contents/development/type-checking.mdx +++ b/docs/contents/development/type-checking.mdx @@ -1,98 +1,24 @@ --- +id: type-checking title: Type Checking with MyPy -description: How the template demonstrates PEP 561 type distribution and static analysis tooling +sidebar_position: 5 --- # Type Checking with MyPy -The Python UV Project Template ships with a minimal `types.py` module and `py.typed` marker to show how to distribute type information (PEP 561) from the start. This page explains how to adapt that example for your project, keep your annotations healthy, and run MyPy with uv. +The SDK ships with typed modules and a `py.typed` marker under `agent_assembly/`. -## PEP Support Out of the Box - -The template configuration aligns with common typing standards: - -- **[PEP 484](https://peps.python.org/pep-0484/)** – Type hints -- **[PEP 585](https://peps.python.org/pep-0585/)** – Generic type hints for built-ins -- **[PEP 561](https://peps.python.org/pep-0561/)** – Distributing type information via `py.typed` -- **[PEP 695](https://peps.python.org/pep-0695/)** – Modern `type` statement alias syntax (Python β‰₯3.12) - -## Where Types Live - -- Default location: `src//types.py` -- Marker file: `src//py.typed` -- Public exports: declare symbols in `__all__` so type checkers know what’s available. - -```python title="src/your_package/types.py" -type Percentage = float -type JSONDict = dict[str, "JSONValue"] -type JSONValue = str | int | float | bool | None | JSONDict | list["JSONValue"] - -__all__ = ["Percentage", "JSONDict", "JSONValue"] -``` - -When you rename the package directory, update the paths in `pyproject.toml`, `.github/workflows/type-check.yml`, and any imports to match your chosen package name. - -## Running MyPy with uv - -The template keeps tooling simple: +## Run MyPy ```bash -# Install dependencies declared in pyproject.toml -uv sync - -# Run mypy on the entire package -uv run mypy src/ - -# Target a submodule or run strict mode on demand -uv run mypy src/your_package/types.py -uv run mypy --strict src/your_package/ +uv run mypy agent_assembly ``` -`pyproject.toml` contains default MyPy settings β€” adjust `mypy.ini` or `pyproject.toml` if you prefer a different configuration style. - -## Pre-commit Hook Integration - -A MyPy hook is already listed in `.pre-commit-config.yaml`. After running `uv sync`, enable the hooks: - -```bash -pre-commit install -pre-commit run mypy --all-files -``` - -This mirrors what happens in CI and prevents untyped or mis-typed code from landing in the main branch. - -## Publishing Types (PEP 561) - -To ensure consumers receive your type information when installing from PyPI: - -1. Keep `py.typed` in the root of your package. -2. Export symbols through `__all__` in `types.py` (or via your package root `__init__.py`). -3. If you restructure files, update `.github/workflows/type-check.yml` so the workflow monitors the correct paths. -4. Uncomment and adjust the `artifacts` entries in `pyproject.toml` (wheel/sdist targets) if you rely on Hatch to copy additional files. - -## Customizing the Example - -1. **Rename the package** – Replace `your_package` everywhere with your actual package name. -2. **Expand `types.py`** – Add Protocols, TypedDicts, Literal types, etc., that match your domain. -3. **Document Types** – Reference your new definitions in docstrings or docs so teammates know they exist. -4. **Add tests** – Validate runtime helpers (type guards, validator helpers) just like any other logic. - -## Type Distribution Workflow - -The template includes `.github/workflows/type-check.yml`, which validates that `types.py` and `py.typed` end up inside distribution artifacts. After you rename your package, update the paths in that workflow (e.g., change `src/your_package/types.py`). See the [PEP 561 Type Distribution Workflow](./ci-cd/type-checking-workflow.mdx) for a full walkthrough. - -## Troubleshooting Checklist - -- **Imports fail in CI** – Ensure the package name in MyPy command matches your src layout (e.g., `uv run mypy src/`). -- **`py.typed` missing** – Confirm the file exists and, if you changed build tools, that it’s included in wheel/sdist artifacts. -- **Pre-commit slows down** – Enable MyPy caching by adding `cache_dir` to configuration or leverage `uv run mypy --dirty` locally. -- **Third-party stubs missing** – Install stub packages via `uv add types-requests` (they’re automatically tracked in `uv.lock`). +## Type artifacts -## Helpful References +- Marker file: `agent_assembly/py.typed` +- Shared aliases: `agent_assembly/types.py` -- [MyPy docs](https://mypy.readthedocs.io/) -- [PEP 561 – Distributing Type Information](https://peps.python.org/pep-0561/) -- [PEP 695 – Type Parameter Syntax](https://peps.python.org/pep-0695/) -- [uv documentation](https://docs.astral.sh/uv/) +## Recommendation -Keep this file tailored to your real codebase once you flesh out the template. Treat the existing content as scaffolding and expand it as your project grows. +Run MyPy locally before opening a PR to keep CI feedback fast. diff --git a/docs/contents/development/workflow.mdx b/docs/contents/development/workflow.mdx index 1b304f2..34bdeec 100644 --- a/docs/contents/development/workflow.mdx +++ b/docs/contents/development/workflow.mdx @@ -4,225 +4,38 @@ title: Development Workflow sidebar_position: 3 --- -```mdx-code-block -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -``` - # Development Workflow -This guide outlines the recommended workflow for contributing to the Python uv project template project. - -## Setting Up Your Environment - -Before you start development, make sure you have completed all the steps in the [Requirements](./requirements.mdx) guide. - -## Development Process - -### 1. Pick or Create an Issue - -- Browse existing [GitHub Issues](https://github.com/Chisanan232/Template-Python-UV-Project/issues) to find something to work on -- If you have a new idea, create a new issue describing the change you want to make -- Comment on the issue to let others know you're working on it - -### 2. Create a Branch - -#### Fork the Repository - -First, fork the project to your own GitHub account: - -1. Go to the [Python uv project template repository](https://github.com/Chisanan232/Template-Python-UV-Project) -2. Click the "Fork" button in the top right -3. Wait for GitHub to create your fork -4. Clone your forked repository to your local machine: - -```bash -# Clone your fork -git clone https://github.com/YOUR_USERNAME/your-repo.git -cd your-repo -``` - -#### Set Up the Upstream Remote - -Add the original repository as an "upstream" remote to keep your fork in sync: +## 1. Sync branch ```bash -# Add the upstream remote -git remote add upstream https://github.com/Chisanan232/Template-Python-UV-Project.git - -# Verify your remotes -git remote -v -``` - -#### Sync with Upstream - -Before creating a new branch, sync your fork with the upstream repository: - -```bash -# Fetch upstream changes -git fetch upstream - -# Checkout your fork's master branch +git fetch origin git checkout master - -# Merge upstream changes -git merge upstream/master - -# Push the changes to your fork -git push origin master +git pull origin master ``` -#### Create a New Branch - -Create a new branch from the updated `master` branch with a descriptive name: +## 2. Create a feature branch ```bash -# Create a new branch -git checkout -b feature/your-feature-name +git checkout -b v0.0.0/AAASM-15/ ``` -Use prefixes like `feature/`, `bugfix/`, `docs/`, or `refactor/` to indicate the type of change. - -### 3. Make Your Changes - -- Follow the [Coding Style and Rules](./coding-style.mdx) -- Keep your changes focused on the issue you're addressing -- Write tests for your changes -- Update documentation as necessary - -### 4. Run Tests Locally - -Before submitting your changes, make sure all tests pass: - - - - ```bash - # Run all tests - pytest - - # Run with coverage report - pytest --cov=your_repo - - # Run specific tests - pytest test/path/to/test_file.py - ``` - - - - ```bash - # Run all tests - poetry run pytest - - # Run with coverage report - poetry run pytest --cov=your_repo - - # Run specific tests - poetry run pytest test/path/to/test_file.py - ``` - - - - ```bash - # Run all tests - uv run pytest - - # Run with coverage report - uv run pytest --cov=your_repo - - # Run specific tests - uv run pytest test/path/to/test_file.py - ``` - - - - -### 5. Run Pre-commit Hooks - -Ensure code quality by running pre-commit hooks: - - - - ```bash - pre-commit run --all-files - ``` - - - - ```bash - poetry run pre-commit run --all-files - ``` - - - - ```bash - uv run pre-commit run --all-files - ``` - - - - -### 6. Commit Your Changes - -Write clear, descriptive commit messages: +## 3. Make and validate changes ```bash -git add . -git commit -m "feat: add websocket transport support" +uv run pytest +uv run ruff check . +uv run mypy agent_assembly ``` -Follow the [Conventional Commits](https://www.conventionalcommits.org/) format: -- `feat:` for new features -- `fix:` for bug fixes -- `docs:` for documentation changes -- `refactor:` for code refactoring -- `test:` for adding or modifying tests -- `chore:` for maintenance tasks - -### 7. Push Your Branch +## 4. Commit and push ```bash -git push origin feature/your-feature-name +git add +git commit -m "" +git push origin ``` -### 8. Create a Pull Request - -- Go to the GitHub repository and create a new pull request -- Provide a clear description of the changes -- Reference the issue number (e.g., "Fixes #123") -- Complete the pull request template - -### 9. Code Review - -- Address any feedback from reviewers -- Make additional commits as needed -- Push updates to your branch - -### 10. Merge - -Once your pull request is approved: -- It will be merged into the main branch -- The CI/CD pipeline will run automatically - -## Continuous Integration - -All pull requests are automatically checked with our [CI/CD pipeline](./ci-cd/index.mdx), which: -- Runs all tests -- Checks code style and quality -- Generates coverage reports -- Builds documentation - -## Release Process - -New releases are created by the core maintainers following this process: - -1. Update version number in relevant files -2. Update the changelog -3. Create a new release branch -4. Create a GitHub release with release notes -5. Publish to PyPI - -## Need Help? +## 5. Open pull request -If you need assistance at any point in the development process: -- Ask questions in the [GitHub Discussions](https://github.com/Chisanan232/Template-Python-UV-Project/discussions) -- Reach out to the maintainers via the contact information in the README +Open a PR to `master` and ensure CI checks are green. From 6394b5519eba4efab9a03729bb0daf1faadebc5c Mon Sep 17 00:00:00 2001 From: Chisanan232 Date: Sat, 25 Apr 2026 20:50:48 +0800 Subject: [PATCH 7/8] =?UTF-8?q?=F0=9F=93=9D=20docs:=20update=20docs=20site?= =?UTF-8?q?=20metadata=20and=20repository=20links?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/README.md | 4 ++-- docs/docusaurus.config.ts | 32 ++++++++++++++++---------------- docs/package.json | 2 +- 3 files changed, 19 insertions(+), 19 deletions(-) diff --git a/docs/README.md b/docs/README.md index 5fa42ba..f919478 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,6 +1,6 @@ -# πŸ“š UV-Template Documentation +# πŸ“š Agent Assembly Python SDK Documentation -Welcome to the documentation site for UV-Template! This site is built using [Docusaurus](https://docusaurus.io/), a modern static website generator. +Welcome to the documentation site for the Agent Assembly Python SDK. This site is built using [Docusaurus](https://docusaurus.io/). ## πŸ—‚οΈ Documentation Structure diff --git a/docs/docusaurus.config.ts b/docs/docusaurus.config.ts index 90982fc..6775c41 100644 --- a/docs/docusaurus.config.ts +++ b/docs/docusaurus.config.ts @@ -5,16 +5,16 @@ import remarkGfm from 'remark-gfm'; import remarkMdxCodeMeta from 'remark-mdx-code-meta'; const config: Config = { - title: 'Python-uv-project-template', - tagline: '🐍 Just a template of Python project be managed by UV.', + title: 'Agent Assembly Python SDK', + tagline: 'Python SDK for AI Agent Assembly governance gateway integration.', favicon: 'img/python_logo_icon.png', // Set the production url of your site here - url: 'https://chisanan232.github.io', + url: 'https://ai-agent-assembly.github.io', // Set the // pathname under which your site is served - baseUrl: '/Template-Python-UV-Project/', - projectName: 'chisanan232.github.io', - organizationName: 'Chisanan232', + baseUrl: '/python-sdk/', + projectName: 'python-sdk', + organizationName: 'AI-agent-assembly', trailingSlash: false, onBrokenLinks: 'warn', @@ -66,7 +66,7 @@ const config: Config = { showLastUpdateTime: true, showLastUpdateAuthor: true, editUrl: - 'https://github.com/Chisanan232/Template-Python-UV-Project/tree/master/docs/', + 'https://github.com/AI-agent-assembly/python-sdk/tree/master/docs/', versions: { current: { label: 'Next', @@ -90,7 +90,7 @@ const config: Config = { showLastUpdateTime: true, showLastUpdateAuthor: true, editUrl: - 'https://github.com/Chisanan232/Template-Python-UV-Project/tree/master/docs/', + 'https://github.com/AI-agent-assembly/python-sdk/tree/master/docs/', versions: { current: { label: 'Next', @@ -109,7 +109,7 @@ const config: Config = { // Options for docusaurus-search-local hashed: true, language: ['en'], - docsRouteBasePath: ['/uv-template'], + docsRouteBasePath: ['/docs', '/dev'], docsDir: ['./contents/document', './contents/development'], highlightSearchTermsOnTargetPage: true, explicitSearchResultPath: true, @@ -129,7 +129,7 @@ const config: Config = { // Replace with your project's social card image: 'img/python_logo_icon.png', navbar: { - title: 'UV-Template', + title: 'Python SDK', logo: { alt: 'My Site Logo', src: 'img/python_logo_icon.png', @@ -165,7 +165,7 @@ const config: Config = { dropdownItemsAfter: [], }, { - href: 'https://github.com/Chisanan232/Template-Python-UV-Project', + href: 'https://github.com/AI-agent-assembly/python-sdk', label: 'GitHub', position: 'right', }, @@ -192,11 +192,11 @@ const config: Config = { items: [ { label: 'GitHub Issues', - href: 'https://github.com/Chisanan232/Template-Python-UV-Project/issues', + href: 'https://github.com/AI-agent-assembly/python-sdk/issues', }, { label: 'GitHub Discussions', - href: 'https://github.com/Chisanan232/Template-Python-UV-Project/discussions', + href: 'https://github.com/AI-agent-assembly/python-sdk/discussions', }, ], }, @@ -205,12 +205,12 @@ const config: Config = { items: [ { label: 'GitHub Repository', - href: 'https://github.com/Chisanan232/Template-Python-UV-Project', + href: 'https://github.com/AI-agent-assembly/python-sdk', }, ], }, ], - copyright: `Copyright ${new Date().getFullYear()} - PRESENT, Python-uv-project-template is owned by @Chisanan232.
Built with Docusaurus.`, + copyright: `Copyright ${new Date().getFullYear()} AI-agent-assembly.
Built with Docusaurus.`, }, prism: { theme: prismThemes.github, @@ -226,7 +226,7 @@ const config: Config = { tagName: 'link', attributes: { rel: 'canonical', - href: 'https://chisanan232.github.io/Template-Python-UV-Project/docs/introduction', + href: 'https://ai-agent-assembly.github.io/python-sdk/docs/introduction', }, }, ], diff --git a/docs/package.json b/docs/package.json index b32f52b..dab5b04 100644 --- a/docs/package.json +++ b/docs/package.json @@ -1,5 +1,5 @@ { - "name": "uv-template-docs", + "name": "agent-assembly-python-sdk-docs", "version": "0.0.0", "private": true, "scripts": { From bd0b35230f188e4223bd5172084b6055e3c94464 Mon Sep 17 00:00:00 2001 From: Chisanan232 Date: Sat, 25 Apr 2026 20:54:53 +0800 Subject: [PATCH 8/8] =?UTF-8?q?=F0=9F=90=9B=20docs:=20fix=20MDX=20autolink?= =?UTF-8?q?s=20that=20broke=20docs=20build?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/contents/document/changelog.mdx | 4 ++-- docs/contents/document/introduction.mdx | 2 +- docs/contents/document/quick-start/requirements.mdx | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/contents/document/changelog.mdx b/docs/contents/document/changelog.mdx index 683d0bc..50f22cc 100644 --- a/docs/contents/document/changelog.mdx +++ b/docs/contents/document/changelog.mdx @@ -8,5 +8,5 @@ sidebar_position: 5 Project history is tracked in GitHub pull requests and release notes. -- Pull requests: -- Releases: +- Pull requests: [AI-agent-assembly/python-sdk PRs](https://github.com/AI-agent-assembly/python-sdk/pulls) +- Releases: [AI-agent-assembly/python-sdk Releases](https://github.com/AI-agent-assembly/python-sdk/releases) diff --git a/docs/contents/document/introduction.mdx b/docs/contents/document/introduction.mdx index 159c538..28eb7c0 100644 --- a/docs/contents/document/introduction.mdx +++ b/docs/contents/document/introduction.mdx @@ -25,6 +25,6 @@ This SDK currently includes: ## Repository -- GitHub: +- GitHub: [AI-agent-assembly/python-sdk](https://github.com/AI-agent-assembly/python-sdk) Use [Quick Start](./quick-start/index.mdx) to get running locally. diff --git a/docs/contents/document/quick-start/requirements.mdx b/docs/contents/document/quick-start/requirements.mdx index 331b797..1ec4328 100644 --- a/docs/contents/document/quick-start/requirements.mdx +++ b/docs/contents/document/quick-start/requirements.mdx @@ -16,4 +16,4 @@ sidebar_position: 1 - `uv` (recommended) - Git -Install `uv` from: +Install `uv` from: [Astral uv docs](https://docs.astral.sh/uv/)