# Standards Documentation Index

This directory contains coding standards, conventions, processes, workflows, and best practices for StarPunk CMS development.

## Core Standards

### Code Quality
- **[python-coding-standards.md](python-coding-standards.md)** - Python code style, patterns, and best practices
- **[utility-function-patterns.md](utility-function-patterns.md)** - Patterns for writing utility functions

### Testing
- **[testing-checklist.md](testing-checklist.md)** - Comprehensive testing checklist and requirements

### Development Workflow
- **[development-setup.md](development-setup.md)** - Development environment setup guide
- **[git-branching-strategy.md](git-branching-strategy.md)** - Git workflow and branching model
- **[versioning-strategy.md](versioning-strategy.md)** - Semantic versioning guidelines
- **[version-implementation-guide.md](version-implementation-guide.md)** - How to implement version changes

### Conventions
- **[cookie-naming-convention.md](cookie-naming-convention.md)** - Cookie naming standards
- **[documentation-organization.md](documentation-organization.md)** - Documentation structure and organization

## Standards by Category

### Python Development
- **python-coding-standards.md** - Style guide, linting, formatting
- **utility-function-patterns.md** - Reusable code patterns

### Version Control & Release Management
- **git-branching-strategy.md** - Branch naming, workflow, PRs
- **versioning-strategy.md** - SemVer guidelines, version bumping
- **version-implementation-guide.md** - Step-by-step version changes

### Quality Assurance
- **testing-checklist.md** - Test coverage requirements, test types

### Development Environment
- **development-setup.md** - Local setup, dependencies, tools

### Project Organization
- **documentation-organization.md** - Where to put what docs
- **cookie-naming-convention.md** - Naming consistency

## How to Use These Standards

### For New Developers
1. **Start here**: [development-setup.md](development-setup.md)
2. **Read**: [python-coding-standards.md](python-coding-standards.md)
3. **Understand**: [git-branching-strategy.md](git-branching-strategy.md)
4. **Reference**: Other standards as needed

### Before Writing Code
- [ ] Review [python-coding-standards.md](python-coding-standards.md)
- [ ] Check [utility-function-patterns.md](utility-function-patterns.md) for reusable patterns
- [ ] Create feature branch per [git-branching-strategy.md](git-branching-strategy.md)

### Before Committing Code
- [ ] Run tests per [testing-checklist.md](testing-checklist.md)
- [ ] Verify code follows [python-coding-standards.md](python-coding-standards.md)
- [ ] Update version if needed per [versioning-strategy.md](versioning-strategy.md)
- [ ] Write clear commit message per [git-branching-strategy.md](git-branching-strategy.md)

### Before Creating PR
- [ ] All tests pass ([testing-checklist.md](testing-checklist.md))
- [ ] Documentation updated ([documentation-organization.md](documentation-organization.md))
- [ ] Version bumped if needed ([version-implementation-guide.md](version-implementation-guide.md))
- [ ] PR follows [git-branching-strategy.md](git-branching-strategy.md)

### When Reviewing Code
- [ ] Check adherence to [python-coding-standards.md](python-coding-standards.md)
- [ ] Verify test coverage per [testing-checklist.md](testing-checklist.md)
- [ ] Confirm naming conventions ([cookie-naming-convention.md](cookie-naming-convention.md))
- [ ] Validate documentation ([documentation-organization.md](documentation-organization.md))

## Key Principles

### Code Quality
- **Simplicity First**: "Every line of code must justify its existence"
- **Explicit Over Implicit**: Clear, readable code over clever tricks
- **Type Hints Required**: All functions must have type hints
- **Docstrings Required**: All public functions must have docstrings

### Testing
- **Test-Driven Development**: Write tests before implementation
- **Coverage Requirements**: Minimum 80% coverage, aim for 90%+
- **Test Types**: Unit, integration, and end-to-end tests
- **No Skipped Tests**: All tests must pass

### Version Control
- **Feature Branches**: All work happens in feature branches
- **Atomic Commits**: One logical change per commit
- **Clear Messages**: Commit messages follow conventional commits format
- **No Direct Commits to Main**: All changes via pull requests

### Versioning
- **Semantic Versioning**: MAJOR.MINOR.PATCH format
- **Version Bumping**: Update version in multiple locations consistently
- **Changelog Maintenance**: Document all user-facing changes
- **Tag Releases**: Git tags match version numbers

## Standards Compliance Checklist

Use this checklist for all code contributions:

### Code Standards
- [ ] Follows Python coding standards
- [ ] Uses approved utility patterns
- [ ] Has type hints on all functions
- [ ] Has docstrings on all public functions
- [ ] Passes linting (flake8, black)

### Testing Standards
- [ ] Unit tests written
- [ ] Integration tests if needed
- [ ] All tests pass
- [ ] Coverage meets minimum (80%)

### Git Standards
- [ ] Feature branch created
- [ ] Commits are atomic
- [ ] Commit messages are clear
- [ ] PR description is complete

### Versioning Standards
- [ ] Version updated if needed
- [ ] Changelog updated
- [ ] Version consistent across files
- [ ] Git tag created for releases

### Documentation Standards
- [ ] Code documented
- [ ] README updated if needed
- [ ] ADR created if architectural
- [ ] Implementation report written

## Enforcing Standards

### Automated Enforcement
- **Pre-commit hooks**: Run linting and formatting
- **CI/CD pipeline**: Run tests and checks
- **Code review**: Human verification of standards

### Manual Verification
- **Checklist review**: Use standards compliance checklist
- **Peer review**: Other developers verify adherence
- **Architect review**: For architectural changes

## Updating Standards

Standards are living documents that evolve:

1. **Propose Change**: Create ADR documenting why
2. **Discuss**: Get team consensus
3. **Update Standard**: Modify the relevant standard document
4. **Announce**: Communicate the change to team
5. **Enforce**: Update CI/CD and tooling

## Related Documentation
- **[../architecture/](../architecture/)** - System architecture
- **[../decisions/](../decisions/)** - Architectural Decision Records
- **[../design/](../design/)** - Feature designs
- **[../reports/](../reports/)** - Implementation reports

---

**Last Updated**: 2025-11-25
**Maintained By**: Documentation Manager Agent
**Total Standards**: 9