nexus-workshops/weevil
1
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases 7 Wiki Activity
Files
c34e4c4deacff98d3a394c0a1c8b7e06bb0e3b3f
weevil/docs/TEMPLATE-PACKAGE-SPEC.md
Eric Ratliff 59f8a7faa3 docs: Update documentation for v1.1.0 template system release 
Comprehensively updates all documentation to reflect the template system
feature shipped in v1.1.0 and plans for v1.2.0 package ecosystem.

README.md:
- Add prominent "What's New in v1.1.0" section highlighting templates
- Expand template documentation with detailed examples and use cases
- Show testing template's 45 tests and professional patterns
- Position templates as "game changer" for FTC learning
- Update command reference and quick start guides
- Add template deep dive section with usage recommendations

TEMPLATE-PACKAGE-SPEC.md:
- Mark Part 1 (Templates) as ✅ COMPLETE in v1.1.0
- Document actual implementation (embedded templates, variable substitution)
- Add "Lessons Learned" section from template development
- Update Part 2 (Packages) to reflect v1.2.0 planning
- Show transition from design to implementation reality
- Maintain comprehensive `weevil add` specification for v1.2.0

ROADMAP.md:
- Mark template system complete in v1.1.0 section
- Add "THE GAME CHANGER" designation for templates
- Feature `weevil add` package system as v1.2.0 "THE NEXT BIG THING"
- List initial 15 packages planned for v1.2.0 launch
- Add "Recent Accomplishments" celebrating v1.1.0 delivery
- Update success metrics with actual achievements
- Show clear progression: templates → packages → debugging

Impact:
- Documentation now reflects production reality (templates shipped!)
- Clear roadmap shows v1.2.0 package ecosystem as next major milestone
- Positions Weevil as transformative for FTC software engineering
- Comprehensive reference for teams learning from template system

All documentation ready for v1.1.0 release tag.
2026-02-02 23:35:20 -06:00

727 lines
18 KiB
Markdown
Raw Blame History

# Weevil Template & Package System - Specification
**Version:** 1.1
**Date:** February 2, 2026
**Status:** Template system ✅ COMPLETE | Package system 📋 Planned for v1.2.0
---
## Executive Summary
This document specifies two complementary features for Weevil:
1. **Template System (v1.1.0)** - ✅ **IMPLEMENTED** - Project scaffolding with professional code templates
2. **`weevil add` Package System (v1.2.0)** - 📋 **PLANNED** - Component package management
Together, these enable teams to start with professional code and extend projects with community-shared components.
---
## Part 1: Template System ✅ IMPLEMENTED in v1.1.0
### Status: COMPLETE
The template system has been fully implemented and shipped in v1.1.0.
### Implementation Summary
**Command Syntax:**
```bash
weevil new <project-name> [--template <name>] [--list-templates]
```
**Delivered Templates:**
1. **`basic`** (default) - Minimal FTC project
- 8 files, ~50 lines of code
- Clean starting point
- Example OpMode placeholder
2. **`testing`** - Professional showcase
- 28 files, ~2,500 lines of code
- 45 comprehensive tests (< 2 sec runtime)
- 3 complete subsystems
- Hardware abstraction layer
- Full documentation
**Key Features Delivered:**
- ✅ Template extraction and overlay system
- ✅ Variable substitution (`{{PROJECT_NAME}}`, etc.)
- ✅ Template validation with helpful errors
- ✅ `--list-templates` command
- ✅ Templates embedded in binary (no external files)
- ✅ Complete test coverage (62 tests passing)
### Template Variable Substitution
Implemented variables:
| Variable | Example Value |
|----------|---------------|
| `{{PROJECT_NAME}}` | `my-robot` |
| `{{PACKAGE_NAME}}` | `myrobot` |
| `{{CREATION_DATE}}` | `2026-02-02T10:30:00Z` |
| `{{WEEVIL_VERSION}}` | `1.1.0` |
| `{{TEMPLATE_NAME}}` | `testing` |
### Testing Template Contents
**Subsystems** (3):
- `MotorCycler.java` - State machine for motor cycling
- `WallApproach.java` - Sensor-based navigation
- `TurnController.java` - Gyro-based turning
**Hardware Layer** (12 files):
- 3 interfaces (MotorController, DistanceSensor, GyroSensor)
- 3 FTC implementations
- 3 mock implementations
- 3 additional interfaces
**Tests** (45 tests):
- Unit tests for each subsystem
- Integration tests
- All passing in < 2 seconds
**Documentation** (6 files):
- DESIGN_AND_TEST_PLAN.md (29 KB)
- TESTING_GUIDE.md (13 KB)
- TESTING_SHOWCASE.md (9 KB)
- ARCHITECTURE.md (6 KB)
- SOLUTION.md (3 KB)
- QUICKSTART.md (5 KB)
### Usage Examples
```bash
# Create with default template
weevil new my-robot
# Create with testing template
weevil new my-robot --template testing
# List available templates
weevil new --list-templates
# Output from list:
# Available templates:
#
# basic (default)
# Minimal FTC project structure
# Perfect for: Teams starting from scratch
# Files: ~10 | Code: ~50 lines
#
# testing
# Professional testing showcase with examples
# Perfect for: Learning best practices
# Files: ~30 | Code: ~2,500 lines | Tests: 45
# Includes:
# • 3 complete subsystems
# • Hardware abstraction layer with mocks
# • 45 passing tests (< 2 seconds)
# • Comprehensive documentation
```
### Implementation Architecture
**Storage:** Templates embedded in binary using `include_dir!` macro
**Directory Structure:**
```
weevil/
├── templates/
│ ├── basic/
│ │ ├── .gitignore
│ │ ├── README.md.template
│ │ ├── settings.gradle
│ │ └── src/... (.gitkeep files)
│ └── testing/
│ ├── .gitignore
│ ├── README.md.template
│ ├── DESIGN_AND_TEST_PLAN.md
│ ├── ... (6 doc files)
│ └── src/
│ ├── main/java/robot/
│ │ ├── hardware/... (6 files)
│ │ ├── subsystems/... (3 files)
│ │ └── opmodes/...
│ └── test/java/robot/
│ ├── hardware/... (3 files)
│ └── subsystems/... (4 files)
```
**Key Implementation Details:**
- Templates complement ProjectBuilder (don't replace it)
- ProjectBuilder creates infrastructure (.weevil.toml, build.gradle.kts, etc.)
- Templates overlay content (source code, docs)
- Files ending in `.template` get variable substitution
- Regular files copied as-is
### Success Metrics (Achieved)
- ✅ 62 tests passing (zero warnings)
- ✅ Testing template has 45 passing tests
- ✅ Clean separation: ProjectBuilder vs Templates
- ✅ Cross-platform compatibility (Windows, Linux, macOS)
- ✅ No template fragmentation (templates don't include build files)
- ✅ Professional code quality in testing template
- ✅ Comprehensive documentation
### Lessons Learned
1. **Don't fight ProjectBuilder** - Templates should complement, not replace infrastructure
2. **Embed in binary** - No external file dependencies
3. **Variable substitution** - Essential for project-specific values
4. **Test thoroughly** - Template extraction, variable substitution, file handling all need tests
5. **Documentation matters** - The testing template's value is in its docs as much as code
---
## Part 2: `weevil add` Command - Package Management System
### Status: PLANNED for v1.2.0
The package management system will allow teams to add pre-built components to existing projects.
### Overview
**Purpose:** Add components to existing Weevil projects
**Version:** v1.2.0
**Priority:** HIGH
**Estimated Effort:** 2-3 weeks
### Command Syntax
```bash
weevil add <package> [OPTIONS]
OPTIONS:
--force Overwrite conflicting files
--merge Attempt to merge conflicts (experimental)
--interactive Prompt for each conflict
--dry-run Preview without adding
--no-deps Don't install dependencies
--dev Add as dev dependency
```
### Package Naming
Hierarchical structure: `scope/category/name/variant`
**Examples:**
```
nexus/hardware/dc-motor/core
nexus/hardware/dc-motor/mock
nexus/hardware/dc-motor/example
nexus/hardware/dc-motor/complete
nexus/subsystems/wall-approach/complete
nexus/examples/autonomous/simple-auto
team1234/sensors/custom-lidar/core
```
**Components:**
- **scope**: Publisher (nexus, team1234, etc.)
- **category**: Type (hardware, subsystems, examples, testing)
- **name**: Component name (dc-motor, wall-approach)
- **variant**: Implementation (core, mock, example, complete)
### Standard Variants
| Variant | Contents | Dependencies |
|---------|----------|--------------|
| `core` | Interface + FTC wrapper | None |
| `mock` | Test double | Requires core |
| `example` | Example OpMode | Requires core |
| `complete` | All of above | Includes all variants |
### Usage Examples
```bash
# Add complete package
weevil add nexus/hardware/dc-motor/complete
# Add specific variant
weevil add nexus/hardware/dc-motor/core
weevil add nexus/hardware/dc-motor/mock --dev
# Add subsystem (auto-installs dependencies)
weevil add nexus/subsystems/wall-approach/complete
# Preview
weevil add nexus/hardware/servo/core --dry-run
# Force overwrite
weevil add nexus/hardware/gyro/complete --force
# Interactive resolution
weevil add nexus/subsystems/turn-controller/core --interactive
```
### Dependency Resolution
Packages declare dependencies in manifest:
```toml
[package]
name = "wall-approach"
scope = "nexus"
category = "subsystems"
version = "1.0.0"
[dependencies]
"nexus/hardware/distance/core" = "^2.0.0"
"nexus/hardware/dc-motor/core" = "^1.0.0"
[dev-dependencies]
"nexus/testing/mock-base" = "^1.0.0"
```
**Automatic Resolution:**
```bash
$ weevil add nexus/subsystems/wall-approach/complete
Resolving dependencies...
Installing:
1. nexus/hardware/distance/core (v2.1.0) - dependency
2. nexus/hardware/dc-motor/core (v1.2.0) - dependency
3. nexus/subsystems/wall-approach/complete (v1.0.0)
✓ Added 3 packages (15 files)
```
### Conflict Handling
#### Default (Skip)
```
⚠ File conflicts detected:
src/main/java/robot/hardware/MotorController.java (exists)
Resolution: Skipping conflicting files
Added:
✓ src/main/java/robot/hardware/FtcMotorController.java
Skipped:
⊗ MotorController.java (already exists)
```
#### Force Mode
```bash
$ weevil add nexus/hardware/dc-motor/core --force
⚠ Warning: --force will overwrite 2 files
Continue? [y/N]: y
✓ Overwrote 2 files, added 3 files
```
#### Interactive Mode
```bash
$ weevil add nexus/hardware/dc-motor/core --interactive
Conflict: MotorController.java
Options:
[s] Skip (keep your file)
[o] Overwrite (use package file)
[d] Show diff
[a] Abort
Choice [s]: d
Diff:
--- Existing
+++ Package
@@ -5,3 +5,5 @@
public interface MotorController {
void setPower(double power);
double getPower();
+ void setMode(RunMode mode);
+ RunMode getMode();
}
Choice [s]:
```
### Package Categories
#### `hardware/*`
Physical hardware abstractions
**Subcategories:**
- `hardware/motors/*` - Motor controllers
- `hardware/sensors/*` - Sensor interfaces
- `hardware/servos/*` - Servo controllers
- `hardware/vision/*` - Camera systems
- `hardware/imu/*` - Gyroscopes
**Standard Variants:** core, mock, example, complete
#### `subsystems/*`
Robot subsystems built on hardware
**Examples:**
- `subsystems/drivetrain/*`
- `subsystems/arm/*`
- `subsystems/intake/*`
**Standard Variants:** core, mock, example, complete
#### `examples/*`
Complete working examples
**Subcategories:**
- `examples/autonomous/*`
- `examples/teleop/*`
- `examples/vision/*`
**Variants:** Usually standalone (no variants)
#### `testing/*`
Testing utilities and patterns
**Examples:**
- `testing/mock-hardware` - Mock collection
- `testing/test-patterns` - Reusable patterns
- `testing/assertions` - Custom assertions
#### `utilities/*`
Helper utilities
**Examples:**
- `utilities/math/*`
- `utilities/telemetry/*`
- `utilities/logging/*`
### Package Manifest
**Example (`package.toml`):**
```toml
[package]
name = "dc-motor"
scope = "nexus"
category = "hardware"
version = "1.2.0"
description = "DC motor controller interface and FTC implementation"
license = "MIT"
authors = ["Nexus Workshops <info@nxgit.dev>"]
[variants]
available = ["core", "mock", "example", "complete"]
default = "complete"
[dependencies]
# Empty for base hardware
[files.core]
include = [
"src/main/java/robot/hardware/MotorController.java",
"src/main/java/robot/hardware/FtcMotorController.java"
]
[files.mock]
include = ["src/test/java/robot/hardware/MockMotorController.java"]
dependencies = ["core"]
[files.example]
include = ["src/main/java/robot/opmodes/examples/MotorExample.java"]
dependencies = ["core"]
[files.complete]
dependencies = ["core", "mock", "example"]
```
### Package Repository
**Location:** https://packages.nxgit.dev (to be implemented)
**Structure:**
```
packages.nxgit.dev/
├── index.json
├── nexus/
│ ├── hardware/
│ │ ├── dc-motor/
│ │ │ ├── package.toml
│ │ │ ├── core.tar.gz
│ │ │ ├── mock.tar.gz
│ │ │ └── complete.tar.gz
│ │ └── distance/...
│ └── subsystems/...
└── team1234/...
```
---
## Supporting Commands (v1.2.0)
### `weevil remove`
Remove installed package
```bash
weevil remove <package> [--prune] [--force]
```
### `weevil search`
Search package registry
```bash
weevil search <query>
Output:
nexus/hardware/mecanum-drive/complete
Mecanum drive system with holonomic control
★★★★★ (342 downloads)
```
### `weevil list`
List packages
```bash
weevil list --installed # Show installed
weevil list --available # Show all available
```
### `weevil info`
Show package details
```bash
weevil info nexus/hardware/dc-motor/complete
Package: nexus/hardware/dc-motor/complete
Version: 1.2.0
Downloads: 1,523
License: MIT
Description:
DC motor controller with interface, FTC implementation,
test mocks, and examples.
```
### `weevil update`
Update packages to latest versions
```bash
weevil update # Update all
weevil update <package> # Update specific
```
---
## Implementation Roadmap
### Phase 1: v1.1.0 ✅ COMPLETE
**Template System:**
- [x] Template storage system (embedded in binary)
- [x] Variable substitution engine
- [x] Basic template (minimal project)
- [x] Testing template (professional showcase)
- [x] `--list-templates` command
- [x] Template validation
- [x] Success/error messages
- [x] Documentation (README, DESIGN_AND_TEST_PLAN, etc.)
- [x] Comprehensive tests (62 tests passing)
- [x] Cross-platform support
**Delivered:**
- Template system fully functional
- Two high-quality templates
- Professional documentation
- 100% test coverage
- Zero warnings in `cargo test`
### Phase 2: v1.2.0 📋 PLANNED (2-3 weeks)
**`weevil add` Package System:**
- [ ] Package registry infrastructure
- [ ] Package manifest format (`package.toml`)
- [ ] Dependency resolver (semver)
- [ ] Conflict detection and resolution
- [ ] File installation system
- [ ] `weevil remove` command
- [ ] `weevil search` command
- [ ] `weevil list` command
- [ ] `weevil info` command
- [ ] `weevil update` command
- [ ] 10+ launch packages
- [ ] Documentation
- [ ] Comprehensive tests
---
## Initial Package Set (v1.2.0 Launch)
**Must Have (10 packages):**
1. nexus/hardware/dc-motor/complete
2. nexus/hardware/servo/complete
3. nexus/hardware/distance/complete
4. nexus/hardware/imu/complete
5. nexus/hardware/color-sensor/complete
6. nexus/subsystems/wall-approach/complete
7. nexus/subsystems/turn-controller/complete
8. nexus/testing/mock-hardware
9. nexus/examples/autonomous/simple-auto
10. nexus/examples/teleop/basic-drive
**Nice to Have (+5):**
11. nexus/hardware/mecanum-drive/complete
12. nexus/subsystems/april-tag/complete
13. nexus/examples/autonomous/complex-auto
14. nexus/utilities/telemetry/dashboard
15. nexus/testing/test-patterns
---
## Strategic Benefits
### For Teams
- **Faster start** - Working code from day one (via templates)
- **Code reuse** - Don't reinvent wheels (via packages)
- **Best practices** - Learn from examples
- **Community** - Share solutions
### For Nexus Workshops
- **Authority** - Set FTC code standards
- **Network effects** - More packages = more value
- **Revenue** - Workshops teach patterns
- **Differentiation** - Unique offering
### For FTC Community
- **Quality** - Raised bar across teams
- **Collaboration** - Build on each other
- **Education** - Professional patterns
- **Innovation** - Focus on unique solutions
---
## Success Metrics
### v1.1.0 (Templates) ✅ ACHIEVED
- [x] Template system implemented
- [x] Testing template includes 45 passing tests
- [x] Professional documentation delivered
- [x] 62 tests passing, zero warnings
- [x] Cross-platform support
- [ ] 50+ teams use testing template (tracking in progress)
- [ ] Used in Nexus Workshops curriculum (planned)
### v1.2.0 (Packages) 📋 PLANNED
- [ ] 20+ quality packages at launch
- [ ] 100+ downloads first month
- [ ] 5+ community packages
- [ ] Active ecosystem
---
## Package Quality Standards (v1.2.0)
**Required (All Packages):**
- ✅ Valid package.toml
- ✅ License specified
- ✅ README included
- ✅ Compiles without errors
**Recommended (Verified Badge):**
- ✅ Tests included
- ✅ Comprehensive docs
- ✅ Interface-based design
- ✅ No hardcoded values
- ✅ Follows naming conventions
**Nexus Verified:**
- All required + recommended
- Professional code quality
- Full test coverage
- Maintained and supported
---
## Open Questions (v1.2.0)
1. **Versioning:** How handle breaking changes? (Semver with pre-release tags)
2. **Testing:** Require tests in packages? (Recommended, not required)
3. **Licensing:** Enforce compliance? (Check but don't block)
4. **Moderation:** Who approves packages? (Automated checks + manual review for Nexus Verified)
5. **Private packages:** Support team-private? (v1.3.0 feature)
6. **Namespaces:** Use team numbers? (Optional, teams can use team1234 as scope)
7. **Binary support:** Allow compiled code? (No, source only)
8. **Update notifications:** Alert on updates? (Yes, via `weevil list --upgradable`)
9. **Code signing:** Security/trust model? (GPG signatures for Nexus Verified, optional for community)
10. **Monorepo:** Where store packages? (Separate repo: weevil-packages)
---
## Future Enhancements
### v1.3.0+
- Package signing (GPG)
- Private registries
- `weevil publish` command
- Package mirrors
- Offline mode
- Additional templates (mecanum, vision, etc.)
### v2.0.0+
- Binary packages
- Pre-built libraries
- Cloud builds
- Team collaboration features
- VS Code integration
---
## References
- **npm** - Node package manager (scopes, registry)
- **Cargo** - Rust package manager (semver, crates.io)
- **FreeBSD Ports** - Package system inspiration
- **Maven Central** - Java repository patterns
- **Homebrew** - macOS package management
---
## Appendix: Comparison Matrix
| Feature | Templates (v1.1.0) | Packages (v1.2.0) |
|---------|-------------------|-------------------|
| **Purpose** | Start projects | Extend projects |
| **When** | Project creation | After creation |
| **Size** | Large (complete projects) | Small (components) |
| **Conflicts** | None (new project) | Possible (merging) |
| **Dependencies** | None | Yes (dependency tree) |
| **Variants** | 2 templates | Many per package |
| **Customization** | Fork template | Use as-is or modify |
| **Updates** | Manual (copy pattern) | `weevil update` |
| **Status** | ✅ Shipped | 📋 Planned |
---
*End of Specification*
**Status:**
- ✅ Part 1 (Templates): COMPLETE in v1.1.0
- 📋 Part 2 (Packages): PLANNED for v1.2.0
**Next Steps:**
1. ✅ Ship v1.1.0 with template system
2. Gather feedback on testing template
3. Begin v1.2.0 package system development
4. Create initial package set
**Contact:** eric@intrepidfusion.com
**Organization:** Nexus Workshops LLC
Reference in New Issue View Git Blame Copy Permalink