# Contributing to TraceRTM

**Last Updated:** 2025-11-21

---

## Getting Started

1. Fork the repository
2. Clone your fork
3. Create a feature branch
4. Make your changes
5. Write tests
6. Submit a pull request

---

## Test Requirements

### Test Naming Convention

All tests must follow the TC-X.Y.Z naming convention:

```
TC-X.Y.Z-[test-name]

Where:
  X = Epic number (1-12)
  Y = Story number (1-9)
  Z = Test case number (1-99)
```

### Test Function Naming

```python
def test_tc_X_Y_Z_description(fixture):
    """
    TC-X.Y.Z: Story Title - Test Case Description
    
    FR: FR-XXX
    Story: X.Y
    Type: Unit|Integration|E2E
    Priority: P0|P1|P2
    
    Given: Precondition
    When: Action
    Then: Expected result
    """
```

### Test Template

Use the template in `tests/TEST-TEMPLATE.py` for all new tests.

### Test Organization

```
tests/
├── unit/              # Unit tests
├── integration/       # Integration tests
├── e2e/              # End-to-end tests
└── conftest.py       # Shared fixtures
```

### Test Traceability

Every test must be linked to:
1. **Functional Requirement (FR)** - What requirement does it test?
2. **User Story** - Which story does it implement?
3. **Test Type** - Unit, Integration, or E2E?
4. **Priority** - P0 (critical), P1 (important), P2 (nice-to-have)?

### Test Coverage Requirements

- Minimum 80% code coverage
- All FRs must have test coverage
- All stories must have test coverage
- Mix of positive, negative, and edge case tests

---

## Running Tests

### Run All Tests
```bash
pytest tests/ -v
```

### Run Specific Test File
```bash
pytest tests/unit/test_models_comprehensive.py -v
```

### Run Specific Test
```bash
pytest tests/unit/test_models_comprehensive.py::TestItemModelComprehensive::test_item_creation_minimal -v
```

### Run with Coverage
```bash
pytest tests/ --cov=src/tracertm --cov-report=html
```

### Run by Marker
```bash
pytest tests/ -m unit          # Unit tests only
pytest tests/ -m integration   # Integration tests only
pytest tests/ -m critical      # Critical tests only
```

---

## Code Style

### Python Style Guide

Follow PEP 8:
- 4 spaces for indentation
- Max line length: 100 characters
- Use type hints where possible
- Use docstrings for all functions

### Naming Conventions

- **Classes:** PascalCase (e.g., `ItemModel`)
- **Functions:** snake_case (e.g., `create_item`)
- **Constants:** UPPER_SNAKE_CASE (e.g., `MAX_ITEMS`)
- **Private:** Leading underscore (e.g., `_internal_method`)

### Imports

```python
# Standard library
import os
import sys

# Third-party
import pytest
from sqlalchemy import Column

# Local
from tracertm.models.item import Item
```

---

## Commit Messages

Use conventional commits:

```
type(scope): description

[optional body]

[optional footer]
```

### Types
- `feat:` New feature
- `fix:` Bug fix
- `test:` Test addition/modification
- `docs:` Documentation
- `refactor:` Code refactoring
- `perf:` Performance improvement
- `chore:` Build/dependency changes

### Examples
```
feat(item): add item versioning
fix(database): handle connection timeout
test(epic-1): add configuration tests
docs(readme): update installation instructions
```

---

## Pull Request Process

1. **Create a branch** from `main`
2. **Write tests** for your changes
3. **Run tests** locally: `pytest tests/ -v`
4. **Check coverage**: `pytest tests/ --cov=src/tracertm`
5. **Update documentation** if needed
6. **Commit with conventional messages**
7. **Push to your fork**
8. **Create a pull request**

### PR Checklist

- [ ] Tests added/updated
- [ ] All tests passing
- [ ] Code coverage maintained (80%+)
- [ ] Documentation updated
- [ ] Commit messages follow convention
- [ ] No breaking changes
- [ ] Linked to issue/story

---

## Code Review

All PRs require:
- ✅ Tests passing
- ✅ Code coverage maintained
- ✅ At least 1 approval
- ✅ No merge conflicts

---

## Documentation

### Docstring Format

```python
def function_name(param1: str, param2: int) -> bool:
    """
    Brief description of what the function does.
    
    Longer description if needed, explaining the purpose,
    behavior, and any important details.
    
    Args:
        param1: Description of param1
        param2: Description of param2
    
    Returns:
        Description of return value
    
    Raises:
        ValueError: When something is invalid
        TypeError: When type is wrong
    
    Example:
        >>> result = function_name("test", 42)
        >>> print(result)
        True
    """
```

---

## Questions?

- Check the [README.md](README.md)
- Review [Test Design](docs/test-design-epic-1.md)
- Check [Test Naming Convention](docs/TEST-NAMING-CONVENTION.md)
- Open an issue

---

**Thank you for contributing to TraceRTM!** 🎉
