diff options
Diffstat (limited to 'doc/roadmap.rst')
| -rw-r--r-- | doc/roadmap.rst | 350 |
1 files changed, 350 insertions, 0 deletions
diff --git a/doc/roadmap.rst b/doc/roadmap.rst new file mode 100644 index 0000000..2ccc703 --- /dev/null +++ b/doc/roadmap.rst @@ -0,0 +1,350 @@ +================================================================================ +Nixtamal Development Roadmap +================================================================================ + +.. role:: ab +.. role:: ac + +------------------------------------------------------------------------------ +Overview +------------------------------------------------------------------------------ + +This roadmap outlines the planned development phases for Nixtamal, from its +initial foundation through its ultimate goal: replacing detsys SBOM and +nixpkgs dependency visualization with a superior, community-driven alternative. + +**Current Status:** Phase 2.5 (Documentation & Website Preparation) + +------------------------------------------------------------------------------ +Phase 1: Foundation ✅ COMPLETED +------------------------------------------------------------------------------ + +**Timeline:** 2024-2025 (Original Development) + +**Goals:** Establish core functionality and architecture + +**Deliverables:** + +✅ Core type system (Input, Lockfile, Manifest) +✅ KDL codec for configuration +✅ JSON codec for lockfiles +✅ Git, Darcs, Pijul VCS support +✅ File and Archive input types +✅ Concurrent prefetching with Eio +✅ Basic CLI (lock, refresh, show) +✅ Nilla framework integration (types) +✅ Test suite foundation + +**Key Decisions:** +- OCaml 5.x with Eio for concurrency +- KDL for configuration format +- JSON for lockfile format +- Result-based error handling +- Property-based testing with QCheck + +**Blockers Resolved:** +- Initial Darcs/Pijul fetcher upstreaming to nixpkgs +- OCaml 5/Eio ecosystem stabilization + +------------------------------------------------------------------------------ +Phase 2: Core Features ✅ COMPLETED +------------------------------------------------------------------------------ + +**Timeline:** 2026-Q1 (Completed 2026-04-14) + +**Goals:** Feature parity with upstream, production readiness + +**Deliverables:** + +✅ **Schema Management** + - Versioned schemas (0.1.1, 0.2.0) + - ``nixtamal upgrade`` command + - Backup and rollback on failure + - Version validation and detection + +✅ **Extended VCS Support** + - Fossil VCS integration + - Nilla prefetch implementation + - Hash algorithm improvements (SRI support) + +✅ **Build System Improvements** + - Cmdliner 2.x compatibility + - Flake integration enhancements + - Cross-compilation support preparation + +✅ **Quality Assurance** + - Lockfile auto-creation + - Comprehensive error messages + - Test coverage infrastructure (bisect_ppx) + - CI/CD pipeline + +✅ **Developer Experience** + - Better error context + - Command help improvements + - Documentation updates + +**Commits:** +- ``4ed722f8`` - Port upstream patches (Cmdliner 2.x, upgrade, Fossil) + +**Technical Debt:** +- Some deprecation warnings suppressed (QCheck API changes) +- Comment preservation in KDL pending KDL v2 + +------------------------------------------------------------------------------ +Phase 2.5: Documentation & Website Preparation 🔄 CURRENT +------------------------------------------------------------------------------ + +**Timeline:** 2026-Q2 (Current) + +**Goals:** Prepare for nixtamal.tech launch and community growth + +**Deliverables:** + +🔄 **Documentation** + ✅ Comprehensive project documentation (this document set) + - API documentation (odoc) + - Tutorial and guide content + - Migration guides (from flakes, npins, niv) + - Man pages for all commands + +🔄 **Website (nixtamal.tech)** + - Static site generation + - Documentation hosting + - Interactive examples + - Community links (XMPP, source) + +📋 **Test Coverage** + ✅ Coverage infrastructure (bisect_ppx) + ✅ Basic test expansion (upgrade, Fossil, lockfile) + 🔄 Coverage target: 50%+ + 🔄 Integration tests + 🔄 Property-based test expansion + +📋 **Community Building** + - Contribution guidelines + - Issue templates + - Security policy + - Code of conduct + +**Success Metrics:** +- Documentation complete and accurate +- Website live with all content +- Test coverage >50% +- First external contribution + +------------------------------------------------------------------------------ +Phase 3: Visual Dependency Graphs 📊 NEXT +------------------------------------------------------------------------------ + +**Timeline:** 2026-Q2/Q3 (Planned) + +**Goals:** Create industry-leading dependency visualization to replace detsys +SBOM and improve upon nixpkgs visualization + +**Deliverables:** + +📋 **Phase 3A: Static Generation (MVP)** + + - ``nixtamal graph`` CLI command + - SVG output for dependency trees + - VCS type icons and indicators + - Version information display + - Stale dependency highlighting + + **Technical Stack:** + - OCaml: ocamlgraph for graph processing + - Layout: Sugiyama or force-directed + - Output: SVG (primary), PNG (secondary) + +📋 **Phase 3B: Interactive Web Component** + + - JavaScript visualization library (D3.js or Cytoscape.js) + - Expandable/collapsible nodes + - Filter by VCS type, update status + - Zoom and pan + - Search functionality + - Export options (SVG, PNG, JSON) + + **Integration:** + - Embed in nixtamal.tech + - CI/CD badge generation + - GitHub/GitLab integration (optional) + +📋 **Phase 3C: Advanced Features** + + - Dependency diff between versions + - License information display + - Security advisory integration + - Dependency health scoring + - Reverse dependency lookup + +**Competitive Advantages:** + +vs. **detsys SBOM**: +- Shows relationships, not just inventory +- Real-time updates (stale checking) +- VCS diversity visualization +- Native Nix integration + +vs. **nixpkgs visualization**: +- Modern, interactive interface +- Better VCS support display +- Stale/frozen indicators +- Per-project graphs (not just nixpkgs) + +**Design Document:** +See ``llm/2026-04-15-dependency-graph-design.md`` for detailed technical +specification. + +**Success Metrics:** +- Graph generation <1s for projects with <100 deps +- Web component loads <3s +- Featured on nixtamal.tech homepage +- Community adoption for SBOM replacement + +------------------------------------------------------------------------------ +Phase 4: Ecosystem & Advanced Features 🔮 FUTURE +------------------------------------------------------------------------------ + +**Timeline:** 2026-Q4+ (Future) + +**Goals:** Mature ecosystem, advanced workflows, optional TUI + +**Potential Deliverables:** + +💡 **TUI (Text User Interface)** + - Optional ncurses-based interface + - Interactive lock/refresh + - Real-time progress display + - Keep CLI as primary interface + +💡 **Migration Tools** + - Import from flakes + - Import from npins + - Import from niv + - Automatic conversion utilities + +💡 **Advanced Lockfile Features** + - Partial updates (update only specific inputs) + - Lockfile merging (monorepo support) + - Lockfile verification/signing + - Distributed lockfile caching + +💡 **Nix Integration** + - NixOS module for system-wide nixtamal + - Home Manager integration (optional, we prefer pure Nix) + - nix-shell integration + - direnv integration + +💡 **Performance & Scale** + - Incremental locking + - Parallel prefetch optimization + - Large monorepo support (>1000 inputs) + - Memory usage optimization + +💡 **Enterprise Features** (if there's demand) + - Private mirror management + - Policy enforcement + - Audit logging + - Team workflows + +------------------------------------------------------------------------------ +Continuous Improvement +------------------------------------------------------------------------------ + +**Ongoing Throughout All Phases:** + +• **Bug fixes** - Priority 0 +• **Security updates** - Priority 0 +• **Documentation updates** - Keep current +• **Performance optimization** - Regular profiling +• **Community support** - Responsive issues/PRs +• **Upstream tracking** - Monitor nixpkgs, OCaml ecosystem + +**Dependency Updates:** + +• Regular OCaml version updates +• Eio ecosystem updates +• KDL library updates (especially v2 when stable) +• Nix ecosystem compatibility + +------------------------------------------------------------------------------ +Release Cadence +------------------------------------------------------------------------------ + +**Versioning:** Semantic Versioning (SemVer) + +**Release Types:** + +**Patch releases (0.x.Y)** + - Bug fixes + - Security patches + - Documentation fixes + - Frequency: As needed + +**Minor releases (0.X.y)** + - New features + - Non-breaking changes + - New VCS support + - Frequency: Monthly during active development + +**Major releases (X.y.z)** + - Breaking changes + - Schema updates (with upgrade path) + - API changes + - Frequency: When necessary, with migration period + +**Current Version:** 0.2.0 (Schema Version) + +**Next Planned:** +- 0.2.1 - Documentation polish +- 0.3.0 - Graph visualization (Phase 3A) +- 1.0.0 - Stable release (after Phase 4 begins) + +------------------------------------------------------------------------------ +Decision Log +------------------------------------------------------------------------------ + +**2024:** Decision to use KDL over JSON/YAML/TOML +*Rationale: Human-readable, semantic richness, no whitespace ambiguity* + +**2024:** Decision to use OCaml over Rust/Go +*Rationale: Type safety, ecosystem familiarity, maintainability* + +**2025:** Decision to support dual workflow (traditional + flakes) +*Rationale: User choice, compatibility, gradual migration* + +**2026:** Decision to port from Darcs to Git +*Rationale: Community accessibility, tooling ecosystem* + +**2026:** Decision to prioritize graph visualization over TUI +*Rationale: Web accessibility, SBOM replacement goal, broader impact* + +**2026:** Decision to self-host vs GitHub +*Rationale: Privacy, independence, philosophical alignment* + +------------------------------------------------------------------------------ +Contributing to the Roadmap +------------------------------------------------------------------------------ + +**How to Influence:** + +1. **Open an issue** describing your use case +2. **Propose a PR** implementing a feature +3. **Discuss in XMPP** real-time chat +4. **Sponsor development** if you need specific features + +**What's Needed:** + +- Phase 2.5: Technical writers, web developers +- Phase 3: Visualization experts, D3.js developers +- Phase 4: Nix ecosystem experts +- Always: OCaml developers, testers, documentation + +**Roadmap Evolution:** + +This roadmap is a living document. As we learn from usage and community +feedback, priorities may shift. The goal remains constant: a better way to +manage Nix dependencies. + +.. vim: set textwidth=80 |