tegwick
3858141ce6
- Extend safe_cli_wrapper() to suppress spurious Click errors for both install and update commands; add success indicators for update output - Add test_update_command_error_suppression to verify error suppression - Expand CLAUDE.md to document all 17 agents with categories - Add Keep a Contributing-File format header to CONTRIBUTING.md - Fix TodoFileGuide URL reference in TODO.md - Add RELEASE_NOTES_v1.0.1.md Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
135 lines
5.0 KiB
Markdown
135 lines
5.0 KiB
Markdown
# Contributing
|
|
|
|
This is a Contributing file, used to specify how the repository is and should stay organized.
|
|
The format is based on [Keep a Contributing-File V0.0.1](https://coulomb.social/open/KeepaContributingfile).
|
|
The structure originates from best practices for setting up python repositories as documented for [PythonVibes](https://coulomb.social/open/PythonVibesGuide).
|
|
Use agent-keepa-contributing-file.md to help maintaining this file.
|
|
|
|
This document outlines how to get started, how we organise work, and how to help maintain the quality & clarity of our contributions.
|
|
|
|
*Thank you for your interest in contributing!*
|
|
|
|
## Getting Started
|
|
|
|
### Prerequisites
|
|
- Python 3.8+ for the core framework
|
|
- Git for version control
|
|
- Make for development commands (optional but recommended)
|
|
- Understanding of AI agent concepts (helpful but not required)
|
|
|
|
### Initial Setup
|
|
1. Fork and clone the repository
|
|
2. Set up virtual environment: `python -m venv .venv && source .venv/bin/activate`
|
|
3. Install dependencies: `make setup-complete` or `pip install -e .`
|
|
4. Verify setup: `make test-quick` or `pytest tests/`
|
|
5. Familiarize yourself with agent system (see CLAUDE.md)
|
|
|
|
## Development Workflow
|
|
|
|
### Project Structure
|
|
This repository follows PythonVibes best practices:
|
|
- `src/kaizen_agentic/` - Core framework source code
|
|
- `agents/` - Specialized agent definitions (17+ agents)
|
|
- `tests/` - Comprehensive test suite
|
|
- `TODO.md` - Current development tasks (Keep a Todofile format)
|
|
- `CHANGELOG.md` - Version history (Keep a Changelog format)
|
|
|
|
### Making Changes
|
|
1. **Create a feature branch**: `git checkout -b feature/your-feature-name`
|
|
2. **Make your changes** following the code standards below
|
|
3. **Write tests** for new functionality
|
|
4. **Run the test suite**: `make test` or `pytest`
|
|
5. **Check code quality**: `make lint` or run `black .` and `flake8 .`
|
|
6. **Update documentation** as needed
|
|
7. **Submit a pull request** with clear description
|
|
|
|
### Testing Requirements
|
|
- All new code must include tests
|
|
- Tests should pass locally before submitting PR
|
|
- Use pytest framework for all tests
|
|
- Aim for good test coverage of new functionality
|
|
|
|
## Code Standards
|
|
|
|
### Python Standards (PythonVibes)
|
|
- Follow PEP 8 style guide (100 character line length)
|
|
- Use type hints for all public APIs
|
|
- Write comprehensive docstrings
|
|
- Use src/ layout for source code
|
|
- Manage dependencies through pyproject.toml
|
|
|
|
### Quality Tools
|
|
- **Formatting**: Black (`black .`)
|
|
- **Linting**: Flake8 (`flake8 .`)
|
|
- **Type Checking**: MyPy (`mypy src/`)
|
|
- **Testing**: Pytest (`pytest`)
|
|
|
|
### Agent Development Standards
|
|
For contributing new agents or improving existing ones:
|
|
- Use consistent YAML frontmatter format
|
|
- Write clear, actionable instructions
|
|
- Define explicit scope and authority boundaries
|
|
- Follow existing agent patterns in `agents/` directory
|
|
|
|
## Types of Contributions
|
|
|
|
We welcome various types of contributions:
|
|
- **Code**: New features, bug fixes, improvements
|
|
- **Agent Definitions**: New specialized agents or agent improvements
|
|
- **Documentation**: README updates, code comments, guides
|
|
- **Testing**: New tests, test improvements, bug reports
|
|
- **Performance**: Optimization improvements and measurements
|
|
|
|
## Issue Reporting
|
|
|
|
When reporting bugs, please include:
|
|
- Clear description of the problem
|
|
- Steps to reproduce the issue
|
|
- Expected vs actual behavior
|
|
- Environment details (Python version, OS)
|
|
- Relevant error messages or logs
|
|
|
|
## Pull Request Process
|
|
|
|
1. **Discuss significant changes** in an issue first
|
|
2. **Keep PRs focused** on a single feature or fix
|
|
3. **Write clear commit messages** following conventional commit format
|
|
4. **Update relevant documentation** including TODO.md and CHANGELOG.md
|
|
5. **Ensure all checks pass** including tests and linting
|
|
6. **Respond to review feedback** promptly and constructively
|
|
|
|
## Agent-Assisted Development
|
|
|
|
This repository includes 17+ specialized agents to assist with development:
|
|
- Use `todo-keeper` for TODO.md maintenance
|
|
- Use `changelog-keeper` for CHANGELOG.md updates
|
|
- Use `contributing-keeper` for this file maintenance
|
|
- See CLAUDE.md for complete agent catalog and usage
|
|
|
|
## Community Guidelines
|
|
|
|
### Kaizen Philosophy
|
|
We follow continuous improvement principles:
|
|
- Quality-first approach to all contributions
|
|
- Regular optimization and refinement
|
|
- Performance measurement and pattern analysis
|
|
- Collaborative problem-solving
|
|
|
|
### Communication
|
|
- Be respectful and constructive in all interactions
|
|
- Use GitHub issues and discussions for project-related communication
|
|
- Share knowledge and help other contributors
|
|
- Follow the project's code of conduct
|
|
|
|
### Recognition
|
|
Contributors are acknowledged in:
|
|
- Release notes and CHANGELOG.md
|
|
- Agent definition attribution
|
|
- Community recognition for significant contributions
|
|
|
|
---
|
|
|
|
**Format**: This file follows [Keep a Contributing-File V0.0.1](https://coulomb.social/open/KeepaContributingfile) with [PythonVibes](https://coulomb.social/open/PythonVibes) best practices integration.
|
|
|
|
**Maintenance**: Use `agent-keepaContributingfile.md` to help maintain this file.
|