toolz/goplt
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: reword phase to epic, update mkdocs

Browse Source
This commit is contained in:
0x1d
2025-11-05 09:28:33 +01:00
parent 65a428534c
commit ace9678f6c
64 changed files with 214 additions and 208 deletions
Download Patch File Download Diff File Expand all files Collapse all files

83
docs/content/stories/epic7/7.1-testing-suite.md Normal file
View File

@@ -0,0 +1,83 @@
# Story 7.1: Comprehensive Testing Suite
## Metadata
- **Story ID**: 7.1
- **Title**: Comprehensive Testing Suite
- **Epic**: 7 - Testing, Documentation & CI/CD
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: 10-12 hours
- **Dependencies**: All previous epics
## Goal
Achieve comprehensive test coverage with unit tests, integration tests, and contract tests.
## Description
This story implements a complete testing suite with >80% code coverage, integration tests using testcontainers, and contract tests for API validation.
## Deliverables
### 1. Unit Tests
- Achieve >80% code coverage for core modules:
- Config loader
- Logger
- Auth service
- Permission resolver
- Module registry
- Use `github.com/stretchr/testify` for assertions
- Use `github.com/golang/mock` or `mockery` for mocks
- Test helpers:
- `testutil.NewTestDB()` - In-memory SQLite for tests
- `testutil.NewTestUser()` - Create test user
- `testutil.NewTestContext()` - Context with user
### 2. Integration Tests
- Install `github.com/testcontainers/testcontainers-go`
- Create integration test suite:
- Full HTTP request flow
- Database operations
- Event bus publishing/consuming
- Background job execution
- Test scenarios:
- User registration → login → API access
- Role assignment → permission check
- Module loading and initialization
- Multi-module interaction
- Create `docker-compose.test.yml`:
- PostgreSQL
- Redis
- Kafka (optional)
- Add test tags: `//go:build integration`
### 3. Contract Tests
- Install `github.com/pact-foundation/pact-go` (optional)
- Create API contract tests:
- Verify API responses match OpenAPI spec
- Test backward compatibility
- Use OpenAPI validator:
- Install `github.com/getkin/kin-openapi`
- Validate request/response against OpenAPI spec
- Generate OpenAPI spec from code annotations
### 4. Load Testing
- Create `perf/` directory with k6 scripts:
- `perf/auth-load.js` - Login endpoint load test
- `perf/api-load.js` - General API load test
- Document performance benchmarks:
- Request latency (p50, p95, p99)
- Throughput (requests/second)
- Resource usage (CPU, memory)
## Acceptance Criteria
- [ ] All tests pass in CI
- [ ] Code coverage >80%
- [ ] Integration tests work with testcontainers
- [ ] Contract tests validate API
- [ ] Load tests are documented
## Files to Create/Modify
- `internal/testutil/` - Test utilities
- `docker-compose.test.yml` - Test containers
- `perf/` - Load test scripts
- All test files across the codebase

68
docs/content/stories/epic7/7.2-documentation.md Normal file
View File

@@ -0,0 +1,68 @@
# Story 7.2: Complete Documentation
## Metadata
- **Story ID**: 7.2
- **Title**: Complete Documentation
- **Epic**: 7 - Testing, Documentation & CI/CD
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: 8-10 hours
- **Dependencies**: All previous epics
## Goal
Create comprehensive documentation covering architecture, API, operations, and developer guides.
## Description
This story creates complete documentation including README, architecture docs, API docs, operations guides, and code examples.
## Deliverables
### 1. Core Documentation
- **README.md**:
- Quick start guide
- Architecture overview
- Installation instructions
- Development setup
- **docs/architecture.md**:
- System architecture diagram
- Module system explanation
- Extension points
- **docs/extension-points.md**:
- How to create a module
- Permission system
- Event bus usage
- Background jobs
### 2. API Documentation
- **docs/api.md**:
- API endpoints documentation
- Authentication flow
- Error codes
- Request/response examples
### 3. Operations Documentation
- **docs/operations.md**:
- Deployment guide
- Monitoring setup
- Troubleshooting
- Grafana dashboards
### 4. Code Examples
- `examples/` directory with sample modules
- Code comments and godoc
- Tutorial examples
## Acceptance Criteria
- [ ] Documentation is complete and accurate
- [ ] All major features are documented
- [ ] Code examples work
- [ ] Documentation is accessible
## Files to Create/Modify
- `README.md` - Main documentation
- `docs/architecture.md` - Architecture docs
- `docs/extension-points.md` - Extension guide
- `docs/api.md` - API documentation
- `docs/operations.md` - Operations guide
- `examples/` - Code examples

51
docs/content/stories/epic7/7.3-cicd-enhancement.md Normal file
View File

@@ -0,0 +1,51 @@
# Story 7.3: CI/CD Pipeline Enhancement
## Metadata
- **Story ID**: 7.3
- **Title**: CI/CD Pipeline Enhancement
- **Epic**: 7 - Testing, Documentation & CI/CD
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: 5-6 hours
- **Dependencies**: 7.1
## Goal
Enhance CI/CD pipeline with comprehensive testing, security scanning, and release automation.
## Description
This story enhances the CI/CD pipeline to run comprehensive tests, perform security scanning, and automate releases with Docker image builds.
## Deliverables
### 1. Enhanced CI Pipeline
- Update `.github/workflows/ci.yml`:
- Run unit tests with coverage
- Run integration tests (with testcontainers)
- Run linters (golangci-lint, gosec)
- Generate coverage report
- Upload artifacts
### 2. Release Workflow
- Add release workflow:
- Semantic versioning
- Tag releases
- Build and push Docker images
- Generate changelog
### 3. Security Scanning
- `gosec` for security issues
- Dependabot for dependency updates
- Trivy for container scanning
## Acceptance Criteria
- [ ] CI pipeline runs all tests
- [ ] Coverage reports are generated
- [ ] Security scanning works
- [ ] Release workflow works
- [ ] Docker images are built and pushed
## Files to Create/Modify
- `.github/workflows/ci.yml` - Enhanced CI
- `.github/workflows/release.yml` - Release workflow
- `.github/dependabot.yml` - Dependabot config

77
docs/content/stories/epic7/7.4-docker-deployment.md Normal file
View File

@@ -0,0 +1,77 @@
# Story 7.4: Docker and Deployment
## Metadata
- **Story ID**: 7.4
- **Title**: Docker and Deployment
- **Epic**: 7 - Testing, Documentation & CI/CD
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: 6-8 hours
- **Dependencies**: All previous epics
## Goal
Create production-ready Docker images and comprehensive deployment guides.
## Description
This story creates multi-stage Dockerfiles, Docker Compose files, and deployment guides for various platforms.
## Deliverables
### 1. Docker Images
- Create multi-stage `Dockerfile`:
- Build stage with Go
- Runtime stage (distroless)
- Health checks
- Proper layer caching
### 2. Docker Compose
- Create `docker-compose.yml` for development:
- Platform service
- PostgreSQL
- Redis
- Kafka (optional)
- Create `docker-compose.prod.yml` for production
### 3. Deployment Guides
- **docs/deployment/kubernetes.md**:
- Kubernetes manifests
- Helm chart (optional)
- Service definitions
- ConfigMap and Secret management
- **docs/deployment/docker.md**:
- Docker Compose deployment
- Environment variables
- Volume mounts
- **docs/deployment/cloud.md**:
- AWS/GCP/Azure deployment notes
- Managed service integration
- Load balancer configuration
### 4. Developer Experience
- Create `Makefile` with common tasks:
- `make dev` - Start dev environment
- `make test` - Run tests
- `make lint` - Run linters
- `make generate` - Generate code
- `make docker-build` - Build Docker image
- `make migrate` - Run migrations
- Add development scripts:
- `scripts/dev.sh` - Start all services
- `scripts/test.sh` - Run test suite
- `scripts/seed.sh` - Seed test data
- Create `.env.example` with all config variables
## Acceptance Criteria
- [ ] Docker images build and run successfully
- [ ] Docker Compose works for development
- [ ] Deployment guides are tested
- [ ] New developers can set up environment in <30 minutes
## Files to Create/Modify
- `Dockerfile` - Multi-stage build
- `docker-compose.yml` - Development compose
- `docker-compose.prod.yml` - Production compose
- `docs/deployment/` - Deployment guides
- `Makefile` - Enhanced with more commands
- `scripts/` - Development scripts

42
docs/content/stories/epic7/README.md Normal file
View File

@@ -0,0 +1,42 @@
# Epic 7: Testing, Documentation & CI/CD
## Overview
Comprehensive test coverage (unit, integration, contract), complete documentation, production-ready CI/CD pipeline, Docker images and deployment guides, and developer tooling.
## Stories
### 7.1 Comprehensive Testing Suite
- [Story: 7.1 - Testing Suite](./7.1-testing-suite.md)
- **Goal:** Achieve comprehensive test coverage with unit tests, integration tests, and contract tests.
- **Deliverables:** Unit tests (>80% coverage), integration tests, contract tests, load tests
### 7.2 Complete Documentation
- [Story: 7.2 - Documentation](./7.2-documentation.md)
- **Goal:** Create comprehensive documentation covering architecture, API, operations, and developer guides.
- **Deliverables:** README, architecture docs, API docs, operations guides, code examples
### 7.3 CI/CD Pipeline Enhancement
- [Story: 7.3 - CI/CD Enhancement](./7.3-cicd-enhancement.md)
- **Goal:** Enhance CI/CD pipeline with comprehensive testing, security scanning, and release automation.
- **Deliverables:** Enhanced CI pipeline, release workflow, security scanning
### 7.4 Docker and Deployment
- [Story: 7.4 - Docker & Deployment](./7.4-docker-deployment.md)
- **Goal:** Create production-ready Docker images and comprehensive deployment guides.
- **Deliverables:** Docker images, Docker Compose, deployment guides, developer tooling
## Deliverables Checklist
- [ ] >80% test coverage
- [ ] Integration test suite
- [ ] Complete documentation
- [ ] Production CI/CD pipeline
- [ ] Docker images and deployment guides
- [ ] Developer tooling and scripts
## Acceptance Criteria
- All tests pass in CI
- Code coverage >80%
- Documentation is complete and accurate
- Docker images build and run successfully
- Deployment guides are tested
- New developers can set up environment in <30 minutes