StarPunk/docs/standards/INDEX.md

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 code style, patterns, and best practices
• utility-function-patterns.md - Patterns for writing utility functions

Testing

• testing-checklist.md - Comprehensive testing checklist and requirements

Development Workflow

• development-setup.md - Development environment setup guide
• git-branching-strategy.md - Git workflow and branching model
• versioning-strategy.md - Semantic versioning guidelines
• version-implementation-guide.md - How to implement version changes

Conventions

• cookie-naming-convention.md - Cookie naming standards
• 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
2. Read: python-coding-standards.md
3. Understand: git-branching-strategy.md
4. Reference: Other standards as needed

Before Writing Code

• Review python-coding-standards.md
• Check utility-function-patterns.md for reusable patterns
• Create feature branch per git-branching-strategy.md

Before Committing Code

• Run tests per testing-checklist.md
• Verify code follows python-coding-standards.md
• Update version if needed per versioning-strategy.md
• Write clear commit message per git-branching-strategy.md

Before Creating PR

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

When Reviewing Code

• Check adherence to python-coding-standards.md
• Verify test coverage per testing-checklist.md
• Confirm naming conventions (cookie-naming-convention.md)
• Validate documentation (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/ - System architecture
• ../decisions/ - Architectural Decision Records
• ../design/ - Feature designs
• ../reports/ - Implementation reports

---

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