diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 00000000..64659cc1 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,81 @@ +## Summary + + + + +## Type of Change + +- [ ] Bug fix (non-breaking change which fixes an issue) +- [ ] New feature (non-breaking change which adds functionality) +- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected) +- [ ] Refactoring (code improvement without changing functionality) +- [ ] Documentation update +- [ ] Performance improvement +- [ ] CI/CD or tooling change +- [ ] Dependency update + +## Related Issues + + + +Fixes # +Relates to # + +## Changes Made + + + +- +- +- + +## Testing + + + +**Test Commands Run:** +- [ ] `uv run nox -s test` (all tests passed, coverage β‰₯ 75%) +- [ ] `uv run nox -s lint -- --pyright --ruff` (no errors) +- [ ] `uv run nox -s fmt` (formatting applied) +- [ ] `uv run pre-commit run --all-files` (all hooks passed) + +**Testing Notes:** + + + +## Pre-Submission Checklist + + + +### Code Quality & Tests +- [ ] All functions/methods have type hints +- [ ] Code has docstrings for public APIs +- [ ] New test files follow `test__*.py` naming convention +- [ ] Tests are meaningful and cover edge cases + +### Dependencies & Documentation +- [ ] Used `uv add` for dependencies (not manual `pyproject.toml` edits) +- [ ] `uv.lock` is updated and committed +- [ ] Documentation updated (`README.md`, `CLAUDE.md`, or `docs/` if applicable) +- [ ] Environment variables documented (if new ones added to `Settings`) + +### Configuration Changes +- [ ] No configuration changes +- OR if config changed: + - [ ] `.env` updated with new variables and defaults + - [ ] `Settings` class updated + - [ ] No secrets committed (use `.env.local` for sensitive values) + +## Breaking Changes + +- [ ] This PR does NOT include breaking changes + + + +**Breaking Changes Details:** + + + +## Additional Notes + + diff --git a/.github/workflows/pr-agent.yml b/.github/workflows/pr-agent.yml index a69c5707..8cf97d33 100644 --- a/.github/workflows/pr-agent.yml +++ b/.github/workflows/pr-agent.yml @@ -22,7 +22,7 @@ jobs: uses: qodo-ai/pr-agent@v0.31 env: CONFIG.CUSTOM_MODEL_MAX_TOKENS: 64000 - CONFIG.MODEL: "gemini/gemini-2.5-flash-preview-05-20" + CONFIG.MODEL: "gemini/gemini-2.5-flash" GITHUB_ACTION.AUTO_DESCRIBE: true GITHUB_ACTION.AUTO_IMPROVE: false GITHUB_ACTION.AUTO_REVIEW: false diff --git a/CLAUDE.md b/CLAUDE.md index 7d0d4eb9..866d4c01 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -242,6 +242,11 @@ GitHub Actions workflows in `.github/workflows/`: All workflows use the same nox commands as local development. +## Pull Request Process + +For comprehensive contribution guidelines, including detailed steps for creating and reviewing Pull Requests, please refer to [CONTRIBUTING.md](CONTRIBUTING.md) in the repository root. + +**Code of Conduct**: All contributors must follow our [Code of Conduct](CODE_OF_CONDUCT.md). We maintain a welcoming, inclusive, and harassment-free environment for everyone. ## Environment Variables Critical environment variables (set in `.env.local`): diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 00000000..8ff9f9cb --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,91 @@ +# Contributor Covenant 3.0 Code of Conduct + +## Our Pledge + +We pledge to make our community welcoming, safe, and equitable for all. + +We are committed to fostering an environment that respects and promotes the dignity, rights, and contributions of all individuals, regardless of characteristics including race, ethnicity, caste, color, age, physical characteristics, neurodiversity, disability, sex or gender, gender identity or expression, sexual orientation, language, philosophy or religion, national or social origin, socio-economic position, level of education, or other status. The same privileges of participation are extended to everyone who participates in good faith and in accordance with this Covenant. + +## Encouraged Behaviors + +While acknowledging differences in social norms, we all strive to meet our community's expectations for positive behavior. We also understand that our words and actions may be interpreted differently than we intend based on culture, background, or native language. + +With these considerations in mind, we agree to behave mindfully toward each other and act in ways that center our shared values, including: + +1. Respecting the **purpose of our community**, our activities, and our ways of gathering. +2. Engaging **kindly and honestly** with others. +3. Respecting **different viewpoints** and experiences. +4. **Taking responsibility** for our actions and contributions. +5. Gracefully giving and accepting **constructive feedback**. +6. Committing to **repairing harm** when it occurs. +7. Behaving in other ways that promote and sustain the **well-being of our community**. + + +## Restricted Behaviors + +We agree to restrict the following behaviors in our community. Instances, threats, and promotion of these behaviors are violations of this Code of Conduct. + +1. **Harassment.** Violating explicitly expressed boundaries or engaging in unnecessary personal attention after any clear request to stop. +2. **Character attacks.** Making insulting, demeaning, or pejorative comments directed at a community member or group of people. +3. **Stereotyping or discrimination.** Characterizing anyone’s personality or behavior on the basis of immutable identities or traits. +4. **Sexualization.** Behaving in a way that would generally be considered inappropriately intimate in the context or purpose of the community. +5. **Violating confidentiality**. Sharing or acting on someone's personal or private information without their permission. +6. **Endangerment.** Causing, encouraging, or threatening violence or other harm toward any person or group. +7. Behaving in other ways that **threaten the well-being** of our community. + +### Other Restrictions + +1. **Misleading identity.** Impersonating someone else for any reason, or pretending to be someone else to evade enforcement actions. +2. **Failing to credit sources.** Not properly crediting the sources of content you contribute. +3. **Promotional materials**. Sharing marketing or other commercial content in a way that is outside the norms of the community. +4. **Irresponsible communication.** Failing to responsibly present content which includes, links or describes any other restricted behaviors. + + +## Reporting an Issue + +Tensions can occur between community members even when they are trying their best to collaborate. Not every conflict represents a code of conduct violation, and this Code of Conduct reinforces encouraged behaviors and norms that can help avoid conflicts and minimize harm. + +When an incident does occur, it is important to report it promptly. To report a possible violation. + +Community Moderators take reports of violations seriously and will make every effort to respond in a timely manner. They will investigate all reports of code of conduct violations, reviewing messages, logs, and recordings, or interviewing witnesses and other participants. Community Moderators will keep investigation and enforcement actions as transparent as possible while prioritizing safety and confidentiality. In order to honor these values, enforcement actions are carried out in private with the involved parties, but communicating to the whole community may be part of a mutually agreed upon resolution. + + +## Addressing and Repairing Harm + +**[NOTE: The remedies and repairs outlined below are suggestions based on best practices in code of conduct enforcement. If your community has its own established enforcement process, be sure to edit this section to describe your own policies.]** + +If an investigation by the Community Moderators finds that this Code of Conduct has been violated, the following enforcement ladder may be used to determine how best to repair harm, based on the incident's impact on the individuals involved and the community as a whole. Depending on the severity of a violation, lower rungs on the ladder may be skipped. + +1) Warning + 1) Event: A violation involving a single incident or series of incidents. + 2) Consequence: A private, written warning from the Community Moderators. + 3) Repair: Examples of repair include a private written apology, acknowledgement of responsibility, and seeking clarification on expectations. +2) Temporarily Limited Activities + 1) Event: A repeated incidence of a violation that previously resulted in a warning, or the first incidence of a more serious violation. + 2) Consequence: A private, written warning with a time-limited cooldown period designed to underscore the seriousness of the situation and give the community members involved time to process the incident. The cooldown period may be limited to particular communication channels or interactions with particular community members. + 3) Repair: Examples of repair may include making an apology, using the cooldown period to reflect on actions and impact, and being thoughtful about re-entering community spaces after the period is over. +3) Temporary Suspension + 1) Event: A pattern of repeated violation which the Community Moderators have tried to address with warnings, or a single serious violation. + 2) Consequence: A private written warning with conditions for return from suspension. In general, temporary suspensions give the person being suspended time to reflect upon their behavior and possible corrective actions. + 3) Repair: Examples of repair include respecting the spirit of the suspension, meeting the specified conditions for return, and being thoughtful about how to reintegrate with the community when the suspension is lifted. +4) Permanent Ban + 1) Event: A pattern of repeated code of conduct violations that other steps on the ladder have failed to resolve, or a violation so serious that the Community Moderators determine there is no way to keep the community safe with this person as a member. + 2) Consequence: Access to all community spaces, tools, and communication channels is removed. In general, permanent bans should be rarely used, should have strong reasoning behind them, and should only be resorted to if working through other remedies has failed to change the behavior. + 3) Repair: There is no possible repair in cases of this severity. + +This enforcement ladder is intended as a guideline. It does not limit the ability of Community Managers to use their discretion and judgment, in keeping with the best interests of our community. + + +## Scope + +This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public or other spaces. Examples of representing our community include using an official email address, posting via an official social media account, or acting as an appointed representative at an online or offline event. + + +## Attribution + +This Code of Conduct is adapted from the Contributor Covenant, version 3.0, permanently available at [https://www.contributor-covenant.org/version/3/0/](https://www.contributor-covenant.org/version/3/0/). + +Contributor Covenant is stewarded by the Organization for Ethical Source and licensed under CC BY-SA 4.0. To view a copy of this license, visit [https://creativecommons.org/licenses/by-sa/4.0/](https://creativecommons.org/licenses/by-sa/4.0/) + +For answers to common questions about Contributor Covenant, see the FAQ at [https://www.contributor-covenant.org/faq](https://www.contributor-covenant.org/faq). Translations are provided at [https://www.contributor-covenant.org/translations](https://www.contributor-covenant.org/translations). Additional enforcement and community guideline resources can be found at [https://www.contributor-covenant.org/resources](https://www.contributor-covenant.org/resources). The enforcement ladder was inspired by the work of [Mozilla’s code of conduct team](https://github.com/mozilla/inclusion). + diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..a388dcba --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,474 @@ +# Contributing to python-uv + +Thank you for your interest in contributing to python-uv! This document provides guidelines and instructions for contributing to this project. + +## Table of Contents + +- [Quick Start for Contributors](#quick-start-for-contributors) +- [Development Setup](#development-setup) +- [Making Changes](#making-changes) +- [Pull Request Process](#pull-request-process) +- [Code Standards](#code-standards) +- [Testing Requirements](#testing-requirements) +- [Documentation Guidelines](#documentation-guidelines) +- [Common Issues](#common-issues) +- [Getting Help](#getting-help) + +## Quick Start for Contributors + +1. **Fork and clone** the repository +2. **Set up** your development environment +3. **Create a branch** for your changes +4. **Make changes** following our code standards +5. **Run tests** and quality checks +6. **Submit a pull request** using our template + +## Development Setup + +### Prerequisites + +- Python 3.10 or higher +- [uv](https://github.com/astral-sh/uv) package manager +- Git +- (Optional) Docker and VSCode with Dev Containers extension + +### Setup Steps + +#### Option 1: Using Dev Container (Recommended) + +```bash +# Clone the repository +git clone https://github.com/a5chin/python-uv.git +cd python-uv + +# Open in VSCode +code . + +# When prompted, click "Reopen in Container" +``` + +#### Option 2: Local Setup + +```bash +# Install uv +curl -LsSf https://astral.sh/uv/install.sh | sh + +# Clone the repository +git clone https://github.com/a5chin/python-uv.git +cd python-uv + +# Install dependencies +uv sync + +# Install pre-commit hooks +uv run pre-commit install +``` + +### Verify Your Setup + +```bash +# Run tests +uv run nox -s test + +# Run linters +uv run nox -s lint -- --pyright --ruff + +# Format code +uv run nox -s fmt +``` + +If all commands complete successfully, you're ready to contribute! + +## Making Changes + +### 1. Create a Feature Branch + +```bash +git checkout -b feature/your-feature-name +``` + +Branch naming conventions: +- `feature/` - New features +- `fix/` - Bug fixes +- `hotfix/` - Hotfix +- `release/` - Release changes + +### 2. Make Your Changes + +Follow these guidelines while making changes: + +- **Write clear, focused commits** - Each commit should represent a single logical change +- **Follow code standards** - See [Code Standards](#code-standards) section +- **Add tests** - All new code should have corresponding tests +- **Update documentation** - Keep docs in sync with code changes + +### 3. Commit Your Changes + +Use descriptive commit messages: + +```bash +# Good commit messages +git commit -m "add: CloudWatch logging support" +git commit -m "fix: Handle None values in Logger.format()" +git commit -m "update: Improve type hints in Settings class" +git commit -m "refactor: Simplify Timer context manager logic" +git commit -m "test: Add edge cases for config loading" +git commit -m "docs: Update contributing guidelines" + +# Avoid +git commit -m "updates" +git commit -m "fix bug" +git commit -m "changes" +``` + +## Pull Request Process + +### Before Submitting + +**You MUST run all quality checks before submitting your PR:** + +```bash +# 1. Format code +uv run nox -s fmt + +# 2. Run linters +uv run nox -s lint -- --pyright --ruff + +# 3. Run tests with coverage +uv run nox -s test + +# 4. Run pre-commit hooks +uv run pre-commit run --all-files +``` + +All checks must pass. PRs with failing checks will not be reviewed. + +### Submitting Your PR + +1. **Push your branch** to your fork: + ```bash + git push origin feature/your-feature-name + ``` + +2. **Create a Pull Request** on GitHub + - The PR template will be auto-populated + - Fill out all sections completely + - Link related issues using `Fixes #123` or `Relates to #456` + +3. **PR Template Sections to Complete:** + + - **Summary** - What and why you made these changes + - **Type of Change** - Select applicable change types + - **Related Issues** - Link to issues + - **Changes Made** - List main changes + - **Testing** - Confirm all test commands passed + - **Pre-Submission Checklist** - Verify all items + - **Breaking Changes** - Document if applicable + - **Additional Notes** - Screenshots, performance notes, etc. + +### PR Review Process + +1. **Automated checks** run on your PR (CI/CD workflows) +2. **Maintainers review** your code using the review checklist +3. **Address feedback** if changes are requested +4. **PR is merged** once approved + +**Review Timeline:** +- Initial review: Within 2-3 business days +- Follow-up reviews: Within 1-2 business days + +## Code Standards + +### General Guidelines + +- **Line length**: Maximum 88 characters (Black-compatible) +- **Python version**: Target Python 3.10+ (or a specific stable version) +- **Import order**: Automatically handled by Ruff +- **Naming conventions**: + - Classes: `PascalCase` + - Functions/variables: `snake_case` + - Constants: `UPPER_SNAKE_CASE` + - Private members: `_leading_underscore` + +### Type Hints + +All functions and methods must have type hints: + +```python +# Good +def process_data(items: list[str], max_count: int = 10) -> dict[str, int]: + """Process items and return statistics.""" + ... + +# Avoid +def process_data(items, max_count=10): + ... +``` + +### Docstrings + +All public functions, classes, and modules must have docstrings: + +```python +def calculate_total(items: list[float], tax_rate: float) -> float: + """Calculate the total price including tax. + + Args: + items: List of item prices. + tax_rate: Tax rate as a decimal (e.g., 0.1 for 10%). + + Returns: + Total price including tax. + + Raises: + ValueError: If tax_rate is negative. + """ + if tax_rate < 0: + raise ValueError("Tax rate cannot be negative") + subtotal = sum(items) + return subtotal * (1 + tax_rate) +``` + +### Code Organization + +- **One class per file** (unless closely related) +- **Group related functions** in modules +- **Keep functions focused** - Single Responsibility Principle +- **Avoid deep nesting** - Maximum 3-4 levels +- **Extract complex logic** into named functions + +### Ruff Rules +Run `uv run ruff check .` to see all violations. + +## Testing Requirements + +### Coverage Requirements + +- **Minimum coverage**: 75% (including branch coverage) +- **Target coverage**: 100% for new code +- **Coverage report**: Generated automatically when running tests + +### Writing Tests + +1. **Location**: Mirror the structure of `tools/` in `tests/` +2. **Naming**: Use `test__*.py` pattern (double underscore) +3. **Structure**: One test file per module + +Example test structure: + +```python +# tests/tools/test__logger.py +import logging +from tools.logger import Logger, LogType + +def test_logger_local_format(): + """Test local logger formatting.""" + logger = Logger(__name__, log_type=LogType.LOCAL) + assert logger.level == logging.INFO + +def test_logger_handles_none(): + """Test logger handles None values correctly.""" + logger = Logger(__name__) + # Test implementation + ... +``` + +### Running Tests + +```bash +# Run all tests with coverage +uv run nox -s test + +# Run specific test file +uv run pytest tests/tools/test__logger.py + +# Run specific test function +uv run pytest tests/tools/test__logger.py::test_logger_local_format + +# View coverage report +open htmlcov/index.html +``` + +### Test Best Practices + +- **Test one thing** per test function +- **Use descriptive names** - `test_logger_handles_none_values` +- **Arrange-Act-Assert** pattern +- **Cover edge cases** - empty inputs, None, boundary values +- **Test error conditions** - expected exceptions +- **Minimize mocking** - Use real objects when possible +- **Independent tests** - No dependencies between tests + +## Documentation Guidelines + +### When to Update Documentation + +Update documentation when you: +- Add new features or utilities +- Change public APIs +- Modify configuration options +- Add environment variables +- Change development workflow +- Fix bugs that were caused by unclear documentation + +### Documentation Files + +- **README.md** - High-level overview, quick start, features +- **CLAUDE.md** - Development workflow for Claude Code users +- **CONTRIBUTING.md** - This file (contribution guidelines) +- **docs/** - Detailed guides and references + - `docs/guides/` - Usage guides and tutorials + - `docs/configurations/` - Configuration references + - `docs/usecases/` - Real-world examples + +### Documentation Standards + +- Use clear, concise language +- Provide code examples for new features +- Include both "how" and "why" explanations +- Keep examples up-to-date with code changes +- Use proper markdown formatting +- Test all code examples before committing + +## Common Issues + +### Test Coverage Below 75% + +**Problem**: Coverage is 72%, below the required 75% + +**Solution**: +```bash +# Check coverage report +uv run nox -s test + +# View detailed HTML report to see uncovered lines +open htmlcov/index.html + +# Add tests for uncovered lines +``` + +### Linting Errors + +**Problem**: `uv run nox -s lint` fails + +**Solution**: +```bash +# Auto-fix Ruff issues +uv run ruff check . --fix + +# Format code +uv run ruff format . + +# Check type errors +uv run pyright + +# If type errors persist, add type hints or use type: ignore with justification +``` + +### Pre-commit Hook Failures + +**Problem**: Git commit is blocked by pre-commit hooks + +**Solution**: +```bash +# See what failed +uv run pre-commit run --all-files + +# Common fixes: +# - Ruff formatting: Auto-fixed by the hook +# - Trailing whitespace: Auto-fixed by the hook +# - JSON/YAML/TOML: Fix syntax errors manually + +# Retry commit after fixes +git add . +git commit -m "Your message" +``` + +### Merge Conflicts + +**Problem**: Your branch has conflicts with main + +**Solution**: +```bash +# Update main branch +git checkout main +git pull origin main + +# Go back to your branch +git checkout your-branch + +# Merge main into your branch +git merge main + +# Resolve conflicts in your editor +# After resolving, stage the files +git add . + +# Complete the merge +git commit -m "Resolve merge conflicts with main" + +# Push updated branch +git push origin your-branch +``` + +### `uv.lock` Out of Sync + +**Problem**: CI fails with dependency resolution errors + +**Solution**: +```bash +# Regenerate lock file +uv lock + +# Commit the updated lock file +git add uv.lock +git commit -m "Update: Regenerate uv.lock" +``` + +### Import Errors in Tests + +**Problem**: Tests fail with `ModuleNotFoundError` + +**Solution**: +```bash +# Ensure dependencies are installed +uv sync + +# If issue persists, check that you're using the correct import paths +# Example: Use `from tools.logger import Logger` not `from logger import Logger` +``` + +## Getting Help + +### Resources + +- **Documentation**: https://a5chin.github.io/python-uv +- **Detailed Contributing Guide**: [CONTRIBUTING.md](CONTRIBUTINGmd) +- **PR Template**: [.github/pull_request_template.md](.github/pull_request_template.md) + +### Questions and Discussions + +- **GitHub Issues**: For bug reports and feature requests +- **GitHub Discussions**: For questions and general discussions +- **Pull Request Comments**: For questions about specific code changes + +--- + +## Summary Checklist + +Before submitting your PR, verify: + +- [ ] Code follows project standards (Ruff, Pyright, type hints, docstrings) +- [ ] All tests pass: `uv run nox -s test` (coverage β‰₯ 75%) +- [ ] Linting passes: `uv run nox -s lint -- --pyright --ruff` +- [ ] Code is formatted: `uv run nox -s fmt` +- [ ] Pre-commit hooks pass: `uv run pre-commit run --all-files` +- [ ] Documentation updated (README, CLAUDE.md, or docs/) +- [ ] New test files follow `test__*.py` naming convention +- [ ] Dependencies added via `uv add` (not manual edits) +- [ ] `uv.lock` is updated and committed +- [ ] PR template is completely filled out +- [ ] Breaking changes are documented (if applicable) +- [ ] Related issues are linked in PR description + +**Thank you for contributing to python-uv! πŸŽ‰** diff --git a/README.md b/README.md index 06146b6a..fae2fe2b 100644 --- a/README.md +++ b/README.md @@ -224,19 +224,22 @@ uv run mkdocs gh-deploy ``` . -β”œβ”€β”€ tools/ # Reusable utility modules -β”‚ β”œβ”€β”€ config/ # Configuration management (Settings, FastAPI config) -β”‚ β”œβ”€β”€ logger/ # Logging utilities (Local & Google Cloud formatters) -β”‚ └── tracer/ # Performance tracing (Timer decorator/context manager) -β”œβ”€β”€ tests/ # Test suite (mirrors tools/ structure) +β”œβ”€β”€ tools/ # Reusable utility modules +β”‚ β”œβ”€β”€ config/ # Configuration management (Settings, FastAPI config) +β”‚ β”œβ”€β”€ logger/ # Logging utilities (Local & Google Cloud formatters) +β”‚ └── tracer/ # Performance tracing (Timer decorator/context manager) +β”œβ”€β”€ tests/ # Test suite (mirrors tools/ structure) β”‚ └── tools/ # Unit tests for utility modules -β”œβ”€β”€ docs/ # MkDocs documentation +β”œβ”€β”€ docs/ # MkDocs documentation β”‚ β”œβ”€β”€ getting-started/ # Setup guides β”‚ β”œβ”€β”€ guides/ # Tool usage guides β”‚ β”œβ”€β”€ configurations/ # Configuration references β”‚ └── usecases/ # Real-world examples -β”œβ”€β”€ .devcontainer/ # Dev Container configuration -β”œβ”€β”€ .github/ # GitHub Actions workflows and reusable actions +β”œβ”€β”€ .devcontainer/ # Dev Container configuration +β”œβ”€β”€ .github/ # GitHub Actions workflows, PR templates, and review checklists +β”œβ”€β”€ CODE_OF_CONDUCT.md # Community Code of Conduct +β”œβ”€β”€ CONTRIBUTING.md # Contribution guidelines +β”œβ”€β”€ CLAUDE.md # Claude Code development guidance β”œβ”€β”€ noxfile.py # Task automation configuration (test, lint, fmt) β”œβ”€β”€ pyproject.toml # Project metadata and dependencies (uv) β”œβ”€β”€ ruff.toml # Ruff linter/formatter configuration