Phil Skentelbery
e589f5bd6c
This commit resolves all documentation issues identified in the comprehensive review: CRITICAL FIXES: - Renumbered duplicate ADRs to eliminate conflicts: * ADR-022-migration-race-condition-fix → ADR-037 * ADR-022-syndication-formats → ADR-038 * ADR-023-microformats2-compliance → ADR-040 * ADR-027-versioning-strategy-for-authorization-removal → ADR-042 * ADR-030-CORRECTED-indieauth-endpoint-discovery → ADR-043 * ADR-031-endpoint-discovery-implementation → ADR-044 - Updated all cross-references to renumbered ADRs in: * docs/projectplan/ROADMAP.md * docs/reports/v1.0.0-rc.5-migration-race-condition-implementation.md * docs/reports/2025-11-24-endpoint-discovery-analysis.md * docs/decisions/ADR-043-CORRECTED-indieauth-endpoint-discovery.md * docs/decisions/ADR-044-endpoint-discovery-implementation.md - Updated README.md version from 1.0.0 to 1.1.0 - Tracked ADR-021-indieauth-provider-strategy.md in git DOCUMENTATION IMPROVEMENTS: - Created comprehensive INDEX.md files for all docs/ subdirectories: * docs/architecture/INDEX.md (28 documents indexed) * docs/decisions/INDEX.md (55 ADRs indexed with topical grouping) * docs/design/INDEX.md (phase plans and feature designs) * docs/standards/INDEX.md (9 standards with compliance checklist) * docs/reports/INDEX.md (57 implementation reports) * docs/deployment/INDEX.md (deployment guides) * docs/examples/INDEX.md (code samples and usage patterns) * docs/migration/INDEX.md (version migration guides) * docs/releases/INDEX.md (release documentation) * docs/reviews/INDEX.md (architectural reviews) * docs/security/INDEX.md (security documentation) - Updated CLAUDE.md with complete folder descriptions including: * docs/migration/ * docs/releases/ * docs/security/ VERIFICATION: - All ADR numbers now sequential and unique (50 total ADRs) - No duplicate ADR numbers remain - All cross-references updated and verified - Documentation structure consistent and well-organized These changes improve documentation discoverability, maintainability, and ensure proper version tracking. All index files follow consistent format with clear navigation guidance. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
170 lines
6.4 KiB
Markdown
170 lines
6.4 KiB
Markdown
# 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
|