v0.9.8 PLAN

nself v0.9.8 - v1.0 Preparation Release

Target: February 2026 Focus: Final feature completeness, polish, and production-readiness before v1.0 Goal: Everything needed for v1.0 LTS with room for QA in v0.9.9

---

Overview

v0.9.8 is the feature-complete release that contains everything v1.0 needs. After this:

• v0.9.9: Pure QA, bug fixes, polish (no new features)
• v1.0.0: Production-ready LTS release

---

Current Status Analysis

✅ What's Complete (v0.9.7)

• Security: 100% (SQL injection fixes, CSP, secrets management, rate limiting, SSL)
• CI/CD: 100% (all 7 workflows passing after latest fixes)
• Multi-Tenancy: 100% (tenant isolation, billing, org management)
• Commands: 31 top-level + 295 subcommands (command consolidation complete)
• Test Coverage: 60% (445 tests across unit, integration, E2E)
• Documentation: ~80% (comprehensive but some gaps)
• Cross-Platform: 100% (macOS, Linux, WSL with Bash 3.2+)
• Enterprise Features: 100% (billing, white-label, OAuth, monitoring)

⚠️ What Needs Completion for v1.0

1. Test Coverage (Priority: Critical)

Current: 60% (445 tests) Target: 80% (700+ tests)

Gaps:

• ✅ Tenant isolation: 100% (just completed)
• ⚠️ Multi-tenant billing: ~40% coverage
• ⚠️ White-label system: ~30% coverage
• ⚠️ OAuth providers (13): ~50% coverage (basic flows tested, edge cases missing)
• ⚠️ Backup system: ~60% coverage (restore, pruning, cloud backup need tests)
• ⚠️ Plugin system: ~20% coverage (architecture exists, needs comprehensive tests)
• ⚠️ Rate limiting: ~50% coverage (nginx integration, whitelist/blacklist need tests)
• ⚠️ Search providers (6): ~40% coverage (switching, indexing need tests)
• ⚠️ Deploy commands: ~50% coverage (server lifecycle, sync, remote need tests)
• ⚠️ Database tools: ~70% coverage (migrations solid, seeding/types need more)

Action Items:

• Add 150+ tests for billing flows (subscription create/update/cancel, usage tracking, invoicing)
• Add 100+ tests for white-label (branding, domains, templates)
• Add 80+ tests for OAuth edge cases (token refresh, account linking, provider failures)
• Add 50+ tests for backup/restore scenarios (incremental, cloud, pruning)
• Add 40+ tests for plugin system (installation, updates, webhooks)

2. Documentation Completeness (Priority: High)

Current: ~80% complete Target: 100% complete

Missing:

• ⚠️ CLI Reference: Missing ~20% of subcommands (have main commands, need all subcommands documented)
• ⚠️ Migration Guides: Have Supabase/Nhost/Firebase migrations planned but not fully documented
• ⚠️ Production Deployment: Missing comprehensive production best practices guide
• ⚠️ Monitoring Guide: Have monitoring stack, need usage guide with dashboards
• ⚠️ Troubleshooting: Have doctor command, need comprehensive troubleshooting guide
• ⚠️ Plugin Development: Have plugin system, need developer guide for creating plugins
• ⚠️ API Reference: Missing complete API reference for custom services
• ⚠️ Architecture Docs: Need deep-dive on system architecture and design decisions

Action Items:

• Complete CLI reference with all 295 subcommands (examples, flags, use cases)
• Write comprehensive migration guides (Supabase, Nhost, Firebase → nself)
• Create production deployment guide (scaling, monitoring, backups, security hardening)
• Document all monitoring dashboards and alert configurations
• Create troubleshooting guide organized by symptom → solution
• Write plugin development guide with step-by-step tutorial
• Generate API reference from OpenAPI/GraphQL schema
• Document architecture with diagrams (C4 model: Context, Container, Component, Code)

3. UX & Polish (Priority: High)

Current: Functional but rough edges Target: Smooth, predictable, helpful

Issues:

• ⚠️ Error messages: Some are technical (show stack traces), need user-friendly messages with fixes
• ⚠️ Progress indicators: Some long operations have no progress feedback
• ⚠️ Validation: Some commands accept invalid input and fail later
• ⚠️ Help text: Inconsistent formatting, some commands have sparse help
• ⚠️ Command aliases: Missing convenient shortcuts (e.g., nself ps → nself status)
• ⚠️ Interactive mode: Some wizards could be more guided
• ⚠️ Color/formatting: Inconsistent use of colors and symbols

Action Items:

• Audit all error messages, convert to actionable format: "Problem X. Run Y to fix."
• Add progress bars for: build, deploy, backup, restore, migrations, provider provisioning
• Add input validation BEFORE execution (fail fast with clear guidance)
• Standardize help text format across all commands (Description, Usage, Examples, Flags)
• Add command aliases (ps, ls, rm, etc.) and document in help
• Improve wizard UX with better prompts, defaults, and explanations
• Standardize color scheme (green=success, red=error, yellow=warning, blue=info, cyan=hint)

4. Performance Optimization (Priority: Medium)

Current: Good for most cases, some bottlenecks Target: Fast everywhere

Known Issues:

• ⚠️ nself build can be slow on large projects (30+ services) - no caching
• ⚠️ nself status queries each container individually - could batch
• ⚠️ nself logs for multiple services is sequential - could parallelize
• ⚠️ Database migrations run synchronously - could optimize with parallel execution where safe
• ⚠️ Backup operations don't show compression progress
• ⚠️ Some bash loops could be optimized (unnecessary subshells, redundant reads)

Action Items:

• Add caching to nself build (only regenerate changed configs)
• Batch Docker API calls in nself status (single query for all containers)
• Parallelize nself logs when following multiple services
• Add parallel migration execution with dependency graph
• Show compression progress during backups
• Optimize bash performance (use arrays instead of loops, minimize subshells)
• Add --fast flag to commands that can trade accuracy for speed

5. Production Readiness Features (Priority: High)

Current: Most features exist, need integration and polish Target: Zero-config production deployment

Missing:

• ⚠️ Health checks: Have basic checks, need comprehensive health endpoints for all services
• ⚠️ Graceful shutdown: Some services don't handle SIGTERM properly
• ⚠️ Resource limits: Can set manually, need smart defaults based on instance size
• ⚠️ Log rotation: Logs grow indefinitely, need automatic rotation
• ⚠️ Automated backups: Can run manually, need scheduled backups with retention
• ⚠️ Monitoring alerts: Have Alertmanager, need pre-configured alert rules
• ⚠️ Zero-downtime deploys: Have blue/green capability, need automated rollback
• ⚠️ Database connection pooling: Have PgBouncer, need auto-configuration

Action Items:

• Add /health and /ready endpoints to all services
• Implement graceful shutdown handlers (finish in-flight requests, close connections)
• Auto-calculate resource limits based on available system resources
• Configure logrotate for all service logs (rotate daily, keep 7 days, compress old)
• Add nself backup schedule to set up automated backups (cron integration)
• Create default alert rules (high CPU, low disk, failed services, slow queries)
• Implement automated rollback on deployment failure (health check based)
• Auto-configure PgBouncer based on connection needs

6. Admin UI (nself-admin) (Priority: Medium)

Current: Basic UI exists in separate repo Target: Feature-complete for v1.0

Status Check Needed:

• Is nself-admin v0.1 ready?
• What features are missing?
• Integration with nself CLI?

Action Items (pending admin UI audit):

• Audit current nself-admin features vs roadmap
• Complete missing features for v0.1 (dashboard, logs, metrics, config editor)
• Test CLI ↔ Admin UI integration (actions trigger, status sync)
• Document admin UI setup and usage

7. Plugin System (Priority: Low)

Current: Architecture exists, Stripe plugin planned Target: Working plugin system with one example plugin

Status:

• Plugin architecture: ✅ Designed
• Plugin CLI commands: ✅ Implemented
• Example plugin (Stripe): ⚠️ Planned but not implemented

Action Items (v0.9.8 or defer to v1.1):

• Option A: Ship v1.0 with plugin architecture but no plugins (document "Coming Soon")
• Option B: Complete Stripe plugin for v0.9.8 (adds scope)
• Recommendation: Option A - plugin system can be v1.1 feature

---

v0.9.8 Scope (Recommended)

🎯 Core Goals

1. Test Coverage: 60% → 80% (add 250+ tests)
2. Documentation: 80% → 100% (complete all guides)
3. UX Polish: Audit and fix all rough edges
4. Performance: Optimize critical paths
5. Production Readiness: Add missing production features

📋 Detailed Tasks

Phase 1: Testing (Week 1-2)

• Add 150 billing tests (subscription lifecycle, usage tracking, invoicing)
• Add 100 white-label tests (branding, domains, templates)
• Add 80 OAuth tests (edge cases, failures, account linking)
• Add 50 backup/restore tests (incremental, cloud, pruning scenarios)
• Add 40 plugin system tests (install, update, webhook handling)
• Add 30 rate limiting tests (nginx integration, whitelist/blacklist)
• Add 20 search provider tests (switching, indexing, queries)
• Add 20 deploy tests (server lifecycle, sync, remote operations)
• Fix any failing tests and improve test infrastructure
• Add CI job to enforce 80% coverage minimum

Phase 2: Documentation (Week 2-3)

• Complete CLI reference (all 295 subcommands with examples)
• Write migration guides (Supabase, Nhost, Firebase)
• Create production deployment guide
• Document monitoring dashboards and alerts
• Write comprehensive troubleshooting guide
• Create plugin development tutorial
• Generate API reference documentation
• Document system architecture with C4 diagrams
• Create video tutorials for common workflows
• Update README with v0.9.8 changes

Phase 3: UX Polish (Week 3-4)

• Audit and improve all error messages (actionable format)
• Add progress indicators to long-running commands
• Add input validation to all commands
• Standardize help text format
• Add command aliases (ps, ls, rm, etc.)
• Improve wizard UX (better prompts, defaults, explanations)
• Standardize color scheme across all output
• Add --dry-run support to destructive commands
• Improve command output formatting (tables, lists, JSON)
• Add --verbose and --quiet modes consistently

Phase 4: Performance (Week 4)

• Add build caching (only regenerate changed configs)
• Batch Docker API calls in status command
• Parallelize log tailing for multiple services
• Optimize bash scripts (arrays, minimize subshells)
• Add compression progress to backups
• Profile and optimize slow commands
• Add --fast flag where applicable
• Document performance benchmarks

Phase 5: Production Features (Week 4-5)

• Add comprehensive health endpoints to all services
• Implement graceful shutdown handlers
• Auto-calculate resource limits
• Configure log rotation for all services
• Implement nself backup schedule command
• Create default alert rules for Alertmanager
• Implement automated rollback on deployment failure
• Auto-configure PgBouncer connection pooling
• Add production deployment checklist command
• Document production best practices

Phase 6: Final Polish (Week 5-6)

• Fix all open GitHub issues
• Address community feedback
• Security audit (run all security scans)
• Performance benchmarking (establish baselines)
• Cross-platform testing (macOS, Linux, WSL)
• Load testing (simulate production scenarios)
• Update all version references to 0.9.8
• Create comprehensive release notes
• Update roadmap for v0.9.9 and v1.0

---

What's NOT in v0.9.8 (Deferred)

🔮 Deferred to v1.1+

• Plugin System Implementation: Architecture exists, but actual plugins (Stripe, etc.) can wait
• Interactive CLI Mode: Nice-to-have, not critical for v1.0
• AI Features: Enhanced analytics, intelligent suggestions - future release
• Advanced Monitoring: Current stack is sufficient, advanced features can wait
• Multi-Region Support: Single-region is sufficient for v1.0
• Kubernetes Enhancements: Basic K8s support exists, advanced features later

🎯 Focused Scope Benefits

• Quality over Features: Perfect what we have rather than add more
• Faster Release: 6 weeks instead of 3+ months
• Lower Risk: Less new code = fewer bugs
• Clear v1.0 Path: v0.9.8 → v0.9.9 (QA) → v1.0 (LTS)

---

Success Criteria

✅ v0.9.8 is Ready When:

1. Test Coverage ≥ 80% - All critical paths tested
2. Documentation = 100% - Every command, every feature documented
3. Zero Known Critical Bugs - All P0/P1 issues resolved
4. All CI/CD Passing - 100% green across all workflows
5. Performance Benchmarks Met - All operations complete within target times
6. Production Checklist Complete - All production-readiness features implemented
7. Cross-Platform Verified - Works perfectly on macOS, Linux, WSL
8. Security Audit Clean - No vulnerabilities in scans

---

Timeline

Estimated Duration: 6 weeks

• Week 1-2: Testing (250+ tests added)
• Week 2-3: Documentation (100% complete)
• Week 3-4: UX Polish (all rough edges fixed)
• Week 4: Performance (optimization complete)
• Week 4-5: Production Features (all features implemented)
• Week 5-6: Final Polish (QA, testing, release prep)

Milestones

• Week 2: Test coverage hits 70%
• Week 3: Documentation reaches 90%
• Week 4: UX audit complete, all issues addressed
• Week 5: Production features implemented and tested
• Week 6: v0.9.8 release candidate ready

---

After v0.9.8: Path to v1.0

v0.9.9 - QA & Bug Fixes (2-3 weeks)

• No New Features - Feature freeze
• Bug Fixes Only - Address all reported issues
• Performance Tuning - Optimize based on feedback
• Documentation Updates - Fix any errors or gaps
• Final Testing - Comprehensive QA across all platforms

v1.0.0 - Production Ready LTS (Target: Q1 2026)

• Long-Term Support - Committed support and maintenance
• Stable API - No breaking changes for 1.x series
• Production Grade - Ready for enterprise deployment
• Complete - All planned features implemented
• Documented - Comprehensive guides and references
• Tested - High coverage, proven reliability
• Performant - Optimized for production workloads

---

Questions to Answer

1. Admin UI Status

• Is nself-admin ready for v0.9.8 integration?
• Should admin UI be bundled or separate?
• What features are missing from admin UI roadmap?

2. Plugin System

• Ship v1.0 with plugin architecture but no plugins?
• Or complete Stripe plugin for v0.9.8?
• Recommendation: Defer plugins to v1.1

3. Testing Priority

• Which test gaps are most critical?
• Can we parallelize test development?
• What test infrastructure improvements needed?

4. Documentation Format

• Keep current markdown docs?
• Build dedicated docs site (Docusaurus, etc.)?
• Recommendation: Keep markdown, add docs site in v1.1

---

Conclusion

v0.9.8 represents the final feature-complete release before v1.0 LTS.

By focusing on:

• Testing (80% coverage)
• Documentation (100% complete)
• Polish (UX, performance, production features)
• Quality (bug fixes, stability, reliability)

We ensure v1.0 is truly production-ready, enterprise-grade, and worth the "1.0" designation.

No new features after v0.9.8 - only QA, polish, and bug fixes in v0.9.9 → v1.0.

This gives us a clear, achievable path to a world-class v1.0 release.

---

Next Steps:

1. Review and approve this plan
2. Create GitHub project board for v0.9.8
3. Break down tasks into issues
4. Assign priorities and timeline
5. Begin Phase 1: Testing