Skip to content

Commit 265c9cb

Browse files
Enhance CONTRIBUTING.md with Testing & CI/CD sections
Fixes #33 ## Changes Made - Enhanced Testing section with comprehensive pytest documentation - Running tests locally (various pytest commands) - Running with coverage reporting - Test markers explanation (unit, integration, slow, scripts) - Writing tests guide with fixture examples - Coverage requirements (10% minimum, 70% target) - Links to example test files - Added CI/CD Pipeline section - Tests workflow (multi-version Python testing) - Code Quality workflow (black, flake8, mypy, bandit) - Publish workflow (automated PyPI releases) - Codecov integration details - Viewing CI results (GitHub UI and CLI) - Troubleshooting CI failures - Added Pre-push Checklist section - Step-by-step local checks before pushing - Quick fix commands for common issues - Recommended pre-commit hook template - Updated Pull Request Process - References Pre-push Checklist as first step - Added coverage requirement (10% minimum) - Updated Table of Contents - Added CI/CD Pipeline - Added Pre-push Checklist 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
1 parent 9b40146 commit 265c9cb

File tree

1 file changed

+333
-12
lines changed

1 file changed

+333
-12
lines changed

CONTRIBUTING.md

Lines changed: 333 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,8 @@ Thank you for your interest in contributing to Lazy_Bird! This document provides
1111
- [Coding Standards](#coding-standards)
1212
- [Adding Framework Presets](#adding-framework-presets)
1313
- [Testing](#testing)
14+
- [CI/CD Pipeline](#cicd-pipeline)
15+
- [Pre-push Checklist](#pre-push-checklist)
1416
- [Documentation](#documentation)
1517

1618
## Code of Conduct
@@ -107,12 +109,13 @@ git push origin feature/your-feature-name
107109

108110
### Before Submitting
109111

110-
1. **Test your changes** thoroughly
111-
2. **Update documentation** if needed
112-
3. **Follow coding standards** (see below)
113-
4. **Ensure tests pass** (if applicable)
114-
5. **Update CHANGELOG** (if significant change)
115-
6. **Rebase on latest main** if needed
112+
1. **Run the [Pre-push Checklist](#pre-push-checklist)** - Verify all checks pass locally
113+
2. **Test your changes** thoroughly
114+
3. **Update documentation** if needed
115+
4. **Follow coding standards** (see below)
116+
5. **Ensure tests pass** and coverage meets minimum 10%
117+
6. **Update CHANGELOG** (if significant change)
118+
7. **Rebase on latest main** if needed
116119

117120
### PR Requirements
118121

@@ -280,6 +283,124 @@ Create a PR with:
280283

281284
## Testing
282285

286+
### Running Tests Locally
287+
288+
Lazy_Bird uses pytest for automated testing. All tests must pass before submitting a PR.
289+
290+
```bash
291+
# Run all tests
292+
pytest
293+
294+
# Run with verbose output
295+
pytest -v
296+
297+
# Run specific test directory
298+
pytest tests/unit/
299+
300+
# Run specific test file
301+
pytest tests/unit/test_init.py
302+
303+
# Run tests matching a pattern
304+
pytest -k "test_version"
305+
```
306+
307+
### Running Tests with Coverage
308+
309+
We aim for 70%+ code coverage. Currently, CI requires minimum 10% coverage.
310+
311+
```bash
312+
# Run tests with coverage report
313+
pytest --cov=lazy_bird --cov-report=term
314+
315+
# Generate detailed HTML coverage report
316+
pytest --cov=lazy_bird --cov-report=html
317+
# Open htmlcov/index.html in your browser
318+
319+
# Check if coverage meets threshold
320+
pytest --cov=lazy_bird --cov-fail-under=10
321+
322+
# Generate coverage XML for CI
323+
pytest --cov=lazy_bird --cov-report=xml
324+
```
325+
326+
### Test Markers
327+
328+
Tests are organized with markers for selective execution:
329+
330+
```bash
331+
# Run only unit tests (fast, isolated)
332+
pytest -m unit
333+
334+
# Run only integration tests (slower, may require services)
335+
pytest -m integration
336+
337+
# Run slow tests
338+
pytest -m slow
339+
340+
# Run script tests
341+
pytest -m scripts
342+
343+
# Skip slow tests
344+
pytest -m "not slow"
345+
```
346+
347+
See `pytest.ini` for marker definitions.
348+
349+
### Writing Tests
350+
351+
Tests use fixtures defined in `tests/conftest.py`. Example:
352+
353+
```python
354+
"""tests/unit/test_example.py"""
355+
import lazy_bird
356+
357+
class TestExample:
358+
"""Test suite for example functionality."""
359+
360+
def test_basic_function(self, temp_dir):
361+
"""Test basic functionality using temp directory fixture."""
362+
# temp_dir is provided by conftest.py
363+
test_file = temp_dir / "test.txt"
364+
test_file.write_text("test content")
365+
366+
assert test_file.exists()
367+
assert test_file.read_text() == "test content"
368+
369+
def test_with_config(self, mock_config):
370+
"""Test using mock configuration fixture."""
371+
# mock_config provides a complete configuration
372+
assert mock_config['project_type'] == 'python'
373+
assert 'project_path' in mock_config
374+
```
375+
376+
### Test File Organization
377+
378+
```
379+
tests/
380+
├── conftest.py # Shared fixtures and configuration
381+
├── unit/ # Unit tests (fast, isolated)
382+
│ ├── test_init.py # Package metadata tests
383+
│ └── test_*.py # Add your unit tests here
384+
├── integration/ # Integration tests (slower)
385+
│ └── test_*.py # Add integration tests here
386+
└── fixtures/ # Test data and mock files
387+
```
388+
389+
### Coverage Requirements
390+
391+
- **Current minimum:** 10% (enforced in CI)
392+
- **Target:** 70%+ coverage
393+
- **New code:** Aim for 80%+ coverage on new features
394+
- **Critical paths:** 100% coverage on core functionality
395+
396+
Coverage is tracked via Codecov and reported on every PR.
397+
398+
### Example Test Files
399+
400+
Reference these for writing your own tests:
401+
- [`tests/unit/test_init.py`](tests/unit/test_init.py) - Package metadata tests
402+
- [`tests/conftest.py`](tests/conftest.py) - Shared fixtures
403+
283404
### Manual Testing
284405
285406
```bash
@@ -293,13 +414,213 @@ Create a PR with:
293414
# 4. Check PR creation
294415
```
295416

296-
### Automated Testing
417+
## CI/CD Pipeline
418+
419+
Lazy_Bird uses GitHub Actions for continuous integration and deployment. All PRs and commits to `main` trigger automated checks.
420+
421+
### Workflows
422+
423+
#### Tests Workflow (`.github/workflows/test.yml`)
424+
425+
Runs on every push and PR to `main` or `develop` branches.
426+
427+
**What it does:**
428+
- Tests across Python versions: 3.8, 3.9, 3.10, 3.11, 3.12
429+
- Runs on Ubuntu Latest
430+
- Installs dependencies from `pyproject.toml`
431+
- Executes pytest with coverage
432+
- Uploads coverage to Codecov (Python 3.11 only)
433+
- Enforces 10% minimum coverage threshold
434+
435+
**Viewing results:**
436+
```bash
437+
# View recent workflow runs
438+
gh run list --limit 5
439+
440+
# View specific run details
441+
gh run view <run-id>
442+
443+
# Download run logs
444+
gh run download <run-id>
445+
```
446+
447+
#### Code Quality Workflow (`.github/workflows/lint.yml`)
448+
449+
Runs code quality checks on every push and PR.
450+
451+
**Checks performed:**
452+
1. **Black** - Code formatting (PEP 8 compliance)
453+
2. **Flake8** - Linting and style guide enforcement
454+
3. **Mypy** - Static type checking (informational)
455+
4. **Bandit** - Security vulnerability scanning
456+
457+
**All checks must pass** for the PR to be mergeable.
458+
459+
#### Publish Workflow (`.github/workflows/publish.yml`)
460+
461+
Automatically publishes to PyPI when a GitHub Release is created.
462+
463+
**Steps:**
464+
1. Builds distribution packages (`sdist` and `wheel`)
465+
2. Publishes to PyPI (on release)
466+
3. Uploads artifacts to GitHub Release
467+
4. Manual dispatch option for TestPyPI
468+
469+
### Codecov Integration
470+
471+
Code coverage is tracked and reported on every commit.
472+
473+
**Features:**
474+
- **Project coverage:** Must maintain 10% minimum
475+
- **Patch coverage:** Informational (won't block builds)
476+
- **Coverage badge:** Shows current coverage in README
477+
- **PR comments:** Codecov bot comments on PRs with coverage changes
478+
479+
**Viewing coverage:**
480+
- Badge in README: Shows overall project coverage
481+
- Codecov dashboard: https://codecov.io/gh/yusufkaraaslan/lazy-bird
482+
- PR comments: Detailed coverage diff for changes
483+
484+
### Viewing CI Results
485+
486+
**On GitHub:**
487+
1. Go to your PR or commit
488+
2. Scroll to bottom to see status checks
489+
3. Click "Details" on any check to view logs
490+
491+
**Via CLI:**
492+
```bash
493+
# List recent runs
494+
gh run list
495+
496+
# Watch a running workflow
497+
gh run watch
498+
499+
# View run details
500+
gh run view <run-id> --log
501+
```
502+
503+
### When CI Fails
504+
505+
#### Test Failures
506+
```bash
507+
# Run the same tests locally
508+
pytest --cov=lazy_bird --cov-report=term
509+
510+
# Run specific failing test
511+
pytest tests/unit/test_init.py::TestPackageMetadata::test_version_exists -v
512+
513+
# Check coverage threshold
514+
pytest --cov=lazy_bird --cov-fail-under=10
515+
```
516+
517+
#### Black Formatting Failures
518+
```bash
519+
# Check what would change
520+
black --check --diff lazy_bird/ tests/
521+
522+
# Auto-fix formatting
523+
black lazy_bird/ tests/
524+
525+
# Commit fixes
526+
git add -A
527+
git commit -m "Fix code formatting with black"
528+
```
529+
530+
#### Flake8 Linting Failures
531+
```bash
532+
# Run flake8 locally
533+
flake8 lazy_bird/ tests/
534+
535+
# View only critical errors
536+
flake8 lazy_bird/ tests/ --select=E9,F63,F7,F82
537+
```
538+
539+
#### Mypy Type Checking Issues
540+
```bash
541+
# Run mypy locally
542+
mypy lazy_bird/ --ignore-missing-imports
543+
544+
# Note: Mypy failures are informational and won't block PRs
545+
```
546+
547+
### CI Configuration Files
548+
549+
- `.github/workflows/test.yml` - Test automation
550+
- `.github/workflows/lint.yml` - Code quality checks
551+
- `.github/workflows/publish.yml` - PyPI publishing
552+
- `.codecov.yml` - Coverage configuration
553+
- `pytest.ini` - Pytest configuration
554+
- `pyproject.toml` - Project dependencies and tool configs
555+
556+
## Pre-push Checklist
557+
558+
Before pushing your changes, run these checks locally to avoid CI failures:
297559

298-
If adding test scripts:
299-
- Place in `tests/` directory
300-
- Follow existing test patterns
301-
- Include positive and negative test cases
302-
- Test error handling
560+
```bash
561+
# 1. Run all tests
562+
pytest
563+
564+
# 2. Check code formatting
565+
black --check --diff lazy_bird/ tests/
566+
567+
# 3. Run linter
568+
flake8 lazy_bird/ tests/
569+
570+
# 4. Check types (optional but recommended)
571+
mypy lazy_bird/ --ignore-missing-imports
572+
573+
# 5. Verify coverage threshold
574+
pytest --cov=lazy_bird --cov-fail-under=10
575+
576+
# 6. Run security scan (optional)
577+
bandit -r lazy_bird/
578+
```
579+
580+
### Quick Fix Commands
581+
582+
If checks fail, fix them quickly:
583+
584+
```bash
585+
# Auto-fix formatting
586+
black lazy_bird/ tests/
587+
588+
# Run tests with verbose output to identify failures
589+
pytest -v
590+
591+
# Generate coverage report to see what's missing
592+
pytest --cov=lazy_bird --cov-report=html
593+
open htmlcov/index.html
594+
```
595+
596+
### Recommended: Pre-commit Hook
597+
598+
Create `.git/hooks/pre-commit` to run checks automatically:
599+
600+
```bash
601+
#!/bin/bash
602+
# Run tests and formatting before commit
603+
604+
echo "Running pre-commit checks..."
605+
606+
# Format code
607+
black lazy_bird/ tests/
608+
609+
# Run tests
610+
pytest --cov=lazy_bird --cov-fail-under=10
611+
612+
if [ $? -ne 0 ]; then
613+
echo "❌ Tests failed. Commit aborted."
614+
exit 1
615+
fi
616+
617+
echo "✅ All checks passed!"
618+
```
619+
620+
Make it executable:
621+
```bash
622+
chmod +x .git/hooks/pre-commit
623+
```
303624

304625
## Documentation
305626

0 commit comments

Comments
 (0)