From fe9184aac1ebbe60bc012ec0f240581282954963 Mon Sep 17 00:00:00 2001 From: Isaac Rodriguez Date: Sat, 15 Nov 2025 14:03:07 -0500 Subject: [PATCH 1/7] docs: add comprehensive contributing guidelines with TDD requirements Add detailed CONTRIBUTING.md file that includes: - Development setup instructions with uv dependency manager - Test-Driven Development (TDD) workflow and requirements - Mandatory unit testing requirements with 75% minimum coverage - Code quality standards and Python style guidelines - Pull request process and commit message conventions - Bug reporting and enhancement suggestion templates - Documentation guidelines and community resources Emphasizes TDD approach as a core requirement and makes it clear that all contributions must include appropriate unit tests. Links to uv installation page to support all operating systems. --- .github/CONTRIBUTING.md | 1 - CONTRIBUTING.md | 433 ++++++++++++++++++++++++++++++++++++++++ 2 files changed, 433 insertions(+), 1 deletion(-) delete mode 100644 .github/CONTRIBUTING.md create mode 100644 CONTRIBUTING.md diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md deleted file mode 100644 index 838a1fa..0000000 --- a/.github/CONTRIBUTING.md +++ /dev/null @@ -1 +0,0 @@ -Add information about contributing to this repo. \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..5b87020 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,433 @@ +# Contributing to Bolt Task Automation + +Thank you for your interest in contributing to Bolt! We welcome contributions from the community and are pleased to have you join us in making Bolt better. + +## Table of Contents + +- [Code of Conduct](#code-of-conduct) +- [Getting Started](#getting-started) +- [Development Setup](#development-setup) +- [Test-Driven Development](#test-driven-development) +- [Making Changes](#making-changes) +- [Testing Requirements](#testing-requirements) +- [Coding Standards](#coding-standards) +- [Commit Messages](#commit-messages) +- [Pull Request Process](#pull-request-process) +- [Reporting Bugs](#reporting-bugs) +- [Suggesting Enhancements](#suggesting-enhancements) +- [Documentation](#documentation) +- [Community](#community) + +## Code of Conduct + +By participating in this project, you agree to maintain a respectful and inclusive environment. We are committed to providing a welcoming experience for everyone, regardless of background or identity. + +## Getting Started + +1. **Fork the repository** on GitHub +2. **Clone your fork** locally: + ```bash + git clone https://github.com/YOUR-USERNAME/bolt.git + cd bolt + ``` +3. **Add the upstream repository**: + ```bash + git remote add upstream https://github.com/abantos/bolt.git + ``` + +## Development Setup + +Bolt uses [uv](https://docs.astral.sh/uv/) for dependency management. Follow these steps to set up your development environment: + +1. **Install uv** (if not already installed): + + Follow the installation instructions for your operating system at: https://docs.astral.sh/uv/getting-started/installation/ + +2. **Sync dependencies**: + ```bash + uv sync + ``` + +3. **Verify your setup** by running the tests: + ```bash + uv run bolt ut + ``` + +### Development Dependencies + +The project includes several development dependencies: +- **pytest**: Test framework +- **pytest-cov**: Code coverage plugin +- **assertpy**: Fluent assertion library +- **conttest**: Continuous testing +- **sphinx**: Documentation generator +- **coverage**: Code coverage measurement + +## Test-Driven Development + +**Bolt follows a Test-Driven Development (TDD) approach.** This means: + +### TDD Workflow + +1. **Write a failing test first** - Before implementing any feature or fix: + - Write a test that describes the expected behavior + - Run the test and confirm it fails (red phase) + +2. **Write the minimum code to pass** - Implement just enough code to make the test pass: + - Focus on making the test green, not on perfection + - Avoid over-engineering at this stage + +3. **Refactor** - Improve the code while keeping tests green: + - Clean up duplication + - Improve naming and structure + - Ensure all tests still pass + +### TDD Benefits in Bolt + +- **Better design**: Tests first leads to more modular, testable code +- **Living documentation**: Tests serve as examples of how to use the code +- **Confidence**: Comprehensive test coverage enables safe refactoring +- **Fewer bugs**: Issues are caught early in development + +### Example TDD Cycle + +```python +# 1. Write a failing test (RED) +def test_task_executes_with_config(): + config = {"param": "value"} + task = MyNewTask() + result = task(config) + assert result.success is True + +# 2. Write minimal code to pass (GREEN) +class MyNewTask(Task): + def execute(self): + return Result(success=True) + +# 3. Refactor (REFACTOR) +# Clean up, add error handling, improve names, etc. +``` + +## Making Changes + +### Branch Naming + +Create a descriptive branch for your changes: + +```bash +git checkout -b feature/add-new-task-type +git checkout -b fix/issue-123-config-parsing +git checkout -b docs/improve-getting-started +``` + +Use prefixes: +- `feature/` - New features +- `fix/` - Bug fixes +- `docs/` - Documentation changes +- `refactor/` - Code refactoring +- `test/` - Test improvements + +### Before You Code + +1. **Check existing issues** - Search for related issues or discussions +2. **Open an issue** for major changes - Discuss your approach before investing significant time +3. **Keep changes focused** - One feature or fix per pull request +4. **Update from upstream** regularly: + ```bash + git fetch upstream + git rebase upstream/master + ``` + +## Testing Requirements + +### Unit Test Requirements + +**All code contributions MUST include unit tests.** Pull requests without appropriate tests will not be merged. + +#### Test Coverage Standards + +- **Minimum coverage**: 75% (enforced by CI) +- **Target coverage**: 85% or higher +- **New code**: Must have 100% coverage for new modules/features +- **Bug fixes**: Must include a test that reproduces the bug + +#### Writing Unit Tests + +Tests are located in the `test/` directory and use `pytest` and `assertpy`: + +```python +import unittest +from assertpy import assert_that +from bolt.api import Task + +class TestMyFeature(unittest.TestCase): + def setUp(self): + """Set up test fixtures""" + self.config = {"param": "value"} + + def test_feature_does_something(self): + """Test should have a descriptive name and docstring""" + # Arrange + task = MyTask() + + # Act + result = task(self.config) + + # Assert + assert_that(result).is_not_none() + assert_that(result.success).is_true() + + def test_feature_handles_error_condition(self): + """Test error cases and edge conditions""" + with self.assertRaises(RequiredConfigurationError): + task = MyTask() + task({}) # Missing required config +``` + +#### Test Organization + +- Mirror the source code structure in `test/` +- Name test files as `test_.py` +- Group related tests in test classes +- Use descriptive test names that explain the behavior being tested + +#### Running Tests + +```bash +# Run all unit tests +uv run bolt ut + +# Run tests with coverage report +uv run bolt lcov + +# Run continuous testing (watches for changes) +uv run bolt ct + +# Run specific test file +uv run pytest test/test_api.py + +# Run specific test +uv run pytest test/test_api.py::TestTask::test_specific_behavior +``` + +### Test Quality Guidelines + +- **Test one thing** - Each test should verify a single behavior +- **Use AAA pattern** - Arrange, Act, Assert +- **Independent tests** - Tests should not depend on each other +- **Fast tests** - Unit tests should run quickly +- **Readable tests** - Use clear names and avoid complex logic in tests +- **Test edge cases** - Include boundary conditions and error scenarios + +## Coding Standards + +### Python Style Guide + +- Follow **PEP 8** style guidelines +- Use **4 spaces** for indentation (no tabs) +- Maximum line length: **88 characters** (Black default) +- Use meaningful variable and function names + +### Code Quality + +- Write **clear, self-documenting code** +- Add **docstrings** for modules, classes, and public methods +- Keep functions **small and focused** (Single Responsibility Principle) +- Avoid **premature optimization** +- Handle **errors gracefully** with appropriate exceptions + +### Documentation Strings + +```python +def register_task(name, dependencies=None): + """Register a task with optional dependencies. + + Args: + name (str): The name of the task to register. + dependencies (list, optional): List of task names this task depends on. + + Returns: + bool: True if registration was successful. + + Raises: + TaskRegistrationError: If a task with the same name already exists. + + Example: + >>> register_task('build', ['clean', 'compile']) + True + """ +``` + +## Commit Messages + +Write clear and meaningful commit messages: + +### Format + +``` +(): + + + +