nexus-workshops/weevil
1
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases 7 Wiki Activity

docs: Update documentation for v1.1.0 template system release

Browse Source 
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.
This commit is contained in:
Eric Ratliff
2026-02-02 23:35:20 -06:00
parent df338987b6
commit 59f8a7faa3
3 changed files with 910 additions and 1101 deletions
Download Patch File Download Diff File Expand all files Collapse all files

562
docs/TEMPLATE-PACKAGE-SPEC.md
View File

@@ -1,8 +1,8 @@
# Weevil Template & Package System - Complete Specification
# Weevil Template & Package System - Specification
**Version:** 1.0
**Version:** 1.1
**Date:** February 2, 2026
**Status:** Ready for implementation
**Status:** Template system ✅ COMPLETE | Package system 📋 Planned for v1.2.0
---
@@ -10,168 +10,185 @@
This document specifies two complementary features for Weevil:
1. **`weevil create` (v1.1.0)** - Project scaffolding with templates
2. **`weevil add` (v1.2.0)** - Package management system
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: `weevil create` Command
## Part 1: Template System ✅ IMPLEMENTED in v1.1.0
### Overview
### Status: COMPLETE
**Purpose:** Generate complete FTC robot projects from templates
The template system has been fully implemented and shipped in v1.1.0.
**Version:** v1.1.0-beta.3
**Priority:** HIGH
### Command Syntax
### Implementation Summary
**Command Syntax:**
```bash
weevil create <project-name> [OPTIONS]
OPTIONS:
--template <name> Template to use (default: "basic")
--path <directory> Where to create project (default: current dir)
--force Overwrite existing directory
--no-init Don't initialize git repository
--dry-run Show what would be created
weevil new <project-name> [--template <name>] [--list-templates]
```
### Templates (v1.1.0)
**Delivered Templates:**
#### Template 1: `basic` (Default)
1. **`basic`** (default) - Minimal FTC project
- 8 files, ~50 lines of code
- Clean starting point
- Example OpMode placeholder
**Purpose:** Minimal starting point
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
**Structure:**
```
my-robot/
├── src/
│ ├── main/java/robot/
│ │ └── opmodes/
│ │ └── BasicOpMode.java
│ └── test/java/robot/
│ └── .gitkeep
├── build.gradle
├── settings.gradle
├── .weevil.toml
├── .gitignore
├── README.md
└── build.bat / build.sh
```
**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)
**Files:** ~10
**Code:** ~50 lines
### Template Variable Substitution
#### Template 2: `testing` (Showcase)
Implemented variables:
**Purpose:** Professional testing demonstration
| 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` |
**Includes:**
- 3 subsystems (MotorCycler, WallApproach, TurnController)
- 6 hardware interfaces + FTC implementations
- 6 test mocks
- 45 passing tests
- Complete documentation (6 files)
### Testing Template Contents
**Files:** ~30
**Code:** ~2,500 lines
**Tests:** 45 (< 2 sec runtime)
**Subsystems** (3):
- `MotorCycler.java` - State machine for motor cycling
- `WallApproach.java` - Sensor-based navigation
- `TurnController.java` - Gyro-based turning
**Documentation:**
- README.md
- DESIGN_AND_TEST_PLAN.md
- TESTING_GUIDE.md
- TESTING_SHOWCASE.md
- SOLUTION.md
- ARCHITECTURE.md
**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 minimal project
weevil create my-robot
# Create with default template
weevil new my-robot
# Create with testing template
weevil create my-robot --template testing
weevil new my-robot --template testing
# Create in specific location
weevil create my-robot --template testing --path ~/ftc-projects
# List available templates
weevil new --list-templates
# Preview without creating
weevil create my-robot --template testing --dry-run
# 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
```
### Variable Substitution
### Implementation Architecture
Templates support variables:
**Storage:** Templates embedded in binary using `include_dir!` macro
| Variable | Description | Example |
|----------|-------------|---------|
| `{{PROJECT_NAME}}` | Project directory name | `my-robot` |
| `{{PACKAGE_NAME}}` | Java package name | `myrobot` |
| `{{CREATION_DATE}}` | ISO 8601 timestamp | `2026-02-02T10:30:00Z` |
| `{{WEEVIL_VERSION}}` | Weevil version | `1.1.0` |
| `{{TEMPLATE_NAME}}` | Template used | `testing` |
**Example:**
```java
// File: src/main/java/robot/subsystems/Example.java
// Generated by Weevil {{WEEVIL_VERSION}} on {{CREATION_DATE}}
package robot.{{PACKAGE_NAME}};
**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)
```
Becomes:
```java
// Generated by Weevil 1.1.0 on 2026-02-02T10:30:00Z
package robot.myrobot;
```
**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 Output
### Success Metrics (Achieved)
```
✓ Created FTC project 'my-robot' using template 'testing'
- ✅ 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
Next steps:
cd my-robot
weevil test # Run 45 tests (< 2 seconds)
weevil build # Build APK
weevil deploy # Deploy to robot
### Lessons Learned
Documentation:
README.md - Project overview
DESIGN_AND_TEST_PLAN.md - System architecture
TESTING_GUIDE.md - Testing patterns
```
### Implementation Notes
**Storage Location:**
```
~/.weevil/templates/
├── basic/
│ ├── template.toml
│ └── files/
└── testing/
├── template.toml
└── files/
```
**Effort Estimate:** 2-3 days
**Complexity:** MEDIUM
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
## 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 projects
**Purpose:** Add components to existing Weevil projects
**Version:** v1.2.0
**Priority:** MEDIUM-HIGH
**Priority:** HIGH
**Estimated Effort:** 2-3 weeks
### Command Syntax
@@ -223,11 +240,11 @@ team1234/sensors/custom-lidar/core
```bash
# Add complete package
weevil add nexus/hardware/dc-motor
weevil add nexus/hardware/dc-motor/complete
# Add specific variant
weevil add nexus/hardware/dc-motor/core
weevil add nexus/hardware/dc-motor/mock
weevil add nexus/hardware/dc-motor/mock --dev
# Add subsystem (auto-installs dependencies)
weevil add nexus/subsystems/wall-approach/complete
@@ -247,6 +264,12 @@ weevil add nexus/subsystems/turn-controller/core --interactive
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"
@@ -257,7 +280,9 @@ Packages declare dependencies in manifest:
**Automatic Resolution:**
```bash
weevil add nexus/subsystems/wall-approach/complete
$ weevil add nexus/subsystems/wall-approach/complete
Resolving dependencies...
Installing:
1. nexus/hardware/distance/core (v2.1.0) - dependency
@@ -287,7 +312,7 @@ Skipped:
#### Force Mode
```bash
weevil add nexus/hardware/dc-motor/core --force
$ weevil add nexus/hardware/dc-motor/core --force
⚠ Warning: --force will overwrite 2 files
Continue? [y/N]: y
@@ -298,7 +323,7 @@ Continue? [y/N]: y
#### Interactive Mode
```bash
weevil add nexus/hardware/dc-motor/core --interactive
$ weevil add nexus/hardware/dc-motor/core --interactive
Conflict: MotorController.java
@@ -415,7 +440,7 @@ dependencies = ["core", "mock", "example"]
### Package Repository
**Location:** https://packages.nxgit.dev
**Location:** https://packages.nxgit.dev (to be implemented)
**Structure:**
```
@@ -433,21 +458,9 @@ packages.nxgit.dev/
└── team1234/...
```
### Implementation Notes
**Effort Estimate:** 2-3 weeks
**Complexity:** HIGH
**Key Components:**
1. Package registry (hosted)
2. Dependency resolver
3. Conflict detector
4. File installer
5. Supporting commands (remove, search, list)
---
## Supporting Commands
## Supporting Commands (v1.2.0)
### `weevil remove`
@@ -507,72 +520,45 @@ weevil update <package> # Update specific
---
## Strategic Benefits
### For Teams
- **Faster start** - Working code immediately
- **Best practices** - Learn from examples
- **Code reuse** - Don't reinvent wheels
- **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 (create)
- [ ] 50+ teams use testing template in first month
- [ ] Positive feedback on quality
- [ ] Used in Nexus Workshops curriculum
- [ ] Documentation complete
### v1.2.0 (add)
- [ ] 20+ quality packages at launch
- [ ] 100+ downloads first month
- [ ] 5+ community packages
- [ ] Active ecosystem
---
## Implementation Roadmap
### Phase 1: v1.1.0 (2-3 days)
### Phase 1: v1.1.0 ✅ COMPLETE
**`weevil create` command:**
- [ ] Template storage system
- [ ] Variable substitution
- [ ] Basic template
- [ ] Testing template
- [ ] Git initialization
- [ ] Success/error messages
- [ ] Documentation
- [ ] Tests
**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
### Phase 2: v1.2.0 (2-3 weeks)
**Delivered:**
- Template system fully functional
- Two high-quality templates
- Professional documentation
- 100% test coverage
- Zero warnings in `cargo test`
**`weevil add` command:**
- [ ] Package registry setup
- [ ] Package manifest format
- [ ] Dependency resolver
- [ ] Conflict detection
- [ ] File installation
- [ ] Remove command
- [ ] Search command
- [ ] List command
### 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
- [ ] Tests
- [ ] Comprehensive tests
---
@@ -601,7 +587,48 @@ weevil update <package> # Update specific
---
## Package Quality Standards
## 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
@@ -624,6 +651,21 @@ weevil update <package> # Update specific
---
## 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+
@@ -632,27 +674,14 @@ weevil update <package> # Update specific
- `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
---
## Open Questions
1. **Versioning:** How handle breaking changes?
2. **Testing:** Require tests in packages?
3. **Licensing:** Enforce compliance?
4. **Moderation:** Who approves packages?
5. **Private packages:** Support team-private?
6. **Namespaces:** Use team numbers?
7. **Binary support:** Allow compiled code?
8. **Update notifications:** Alert on updates?
9. **Code signing:** Security/trust model?
10. **Monorepo:** Where store templates/packages?
- VS Code integration
---
@@ -666,102 +695,33 @@ weevil update <package> # Update specific
---
## Appendix: Complete Examples
## Appendix: Comparison Matrix
### Example 1: Creating Project
```bash
$ weevil create my-robot --template testing
Creating FTC project 'my-robot'...
✓ Created directory structure
✓ Generated source files (17 files)
✓ Generated test files (4 files)
✓ Created build configuration
✓ Generated documentation (6 files)
✓ Initialized Git repository
Project created successfully!
Next steps:
cd my-robot
weevil test # 45 tests pass in < 2 sec
weevil build # Build APK
weevil deploy --auto # Deploy to robot
Documentation:
README.md - Overview
DESIGN_AND_TEST_PLAN.md - Architecture
TESTING_GUIDE.md - How to test
```
### Example 2: Adding Package
```bash
$ cd my-robot
$ weevil add nexus/subsystems/mecanum-drive/complete
Resolving dependencies...
Package nexus/subsystems/mecanum-drive/complete requires:
- nexus/hardware/dc-motor/core (v1.2.0)
- nexus/hardware/imu/core (v2.0.0)
Installing 3 packages:
1. nexus/hardware/dc-motor/core (v1.2.0)
2. nexus/hardware/imu/core (v2.0.0)
3. nexus/subsystems/mecanum-drive/complete (v2.1.0)
✓ Added 12 source files
✓ Added 8 test files
✓ Updated build.gradle
Package installed successfully!
Next steps:
See docs/subsystems/MECANUM_DRIVE.md for usage
Run weevil test to verify integration
```
### Example 3: Handling Conflicts
```bash
$ weevil add nexus/hardware/dc-motor/core
⚠ File conflict detected:
src/main/java/robot/hardware/MotorController.java (exists)
Options:
1. Skip conflicting files (safe, default)
2. Overwrite conflicting files (--force)
3. Interactive resolution (--interactive)
4. Abort
Choice [1]: 1
Added:
✓ src/main/java/robot/hardware/FtcMotorController.java
✓ docs/hardware/DC_MOTOR.md
Skipped:
⊗ src/main/java/robot/hardware/MotorController.java
Package partially installed (1 file skipped)
Note: Package may not work correctly if required files skipped
Consider using --force or --interactive for complete installation
```
| 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:** Ready for Implementation
**Status:**
- ✅ Part 1 (Templates): COMPLETE in v1.1.0
- 📋 Part 2 (Packages): PLANNED for v1.2.0
**Next Steps:**
1. Implement `weevil create` for v1.1.0-beta.3
2. Use testing showcase as `testing` template
3. Plan v1.2.0 package system
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