Considering moving some features to 1.1.0 and 1.2.0.
Considering pulling in features that auto generate code or pull in packages. The code generation is planned to bring into v1.1.0 and the document in this commit walks through that decision in great detail.
This commit is contained in:
Eric Ratliff
767
docs/TEMPLATE-PACKAGE-SPEC.md
Normal file
767
docs/TEMPLATE-PACKAGE-SPEC.md
Normal file
@@ -0,0 +1,767 @@
|
|||||||
|
# Weevil Template & Package System - Complete Specification
|
||||||
|
|
||||||
|
**Version:** 1.0
|
||||||
|
**Date:** February 2, 2026
|
||||||
|
**Status:** Ready for implementation
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Executive Summary
|
||||||
|
|
||||||
|
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
|
||||||
|
|
||||||
|
Together, these enable teams to start with professional code and extend projects with community-shared components.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Part 1: `weevil create` Command
|
||||||
|
|
||||||
|
### Overview
|
||||||
|
|
||||||
|
**Purpose:** Generate complete FTC robot projects from templates
|
||||||
|
|
||||||
|
**Version:** v1.1.0-beta.3
|
||||||
|
**Priority:** HIGH
|
||||||
|
|
||||||
|
### 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
|
||||||
|
```
|
||||||
|
|
||||||
|
### Templates (v1.1.0)
|
||||||
|
|
||||||
|
#### Template 1: `basic` (Default)
|
||||||
|
|
||||||
|
**Purpose:** Minimal starting point
|
||||||
|
|
||||||
|
**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
|
||||||
|
```
|
||||||
|
|
||||||
|
**Files:** ~10
|
||||||
|
**Code:** ~50 lines
|
||||||
|
|
||||||
|
#### Template 2: `testing` (Showcase)
|
||||||
|
|
||||||
|
**Purpose:** Professional testing demonstration
|
||||||
|
|
||||||
|
**Includes:**
|
||||||
|
- 3 subsystems (MotorCycler, WallApproach, TurnController)
|
||||||
|
- 6 hardware interfaces + FTC implementations
|
||||||
|
- 6 test mocks
|
||||||
|
- 45 passing tests
|
||||||
|
- Complete documentation (6 files)
|
||||||
|
|
||||||
|
**Files:** ~30
|
||||||
|
**Code:** ~2,500 lines
|
||||||
|
**Tests:** 45 (< 2 sec runtime)
|
||||||
|
|
||||||
|
**Documentation:**
|
||||||
|
- README.md
|
||||||
|
- DESIGN_AND_TEST_PLAN.md
|
||||||
|
- TESTING_GUIDE.md
|
||||||
|
- TESTING_SHOWCASE.md
|
||||||
|
- SOLUTION.md
|
||||||
|
- ARCHITECTURE.md
|
||||||
|
|
||||||
|
### Usage Examples
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Create minimal project
|
||||||
|
weevil create my-robot
|
||||||
|
|
||||||
|
# Create with testing template
|
||||||
|
weevil create my-robot --template testing
|
||||||
|
|
||||||
|
# Create in specific location
|
||||||
|
weevil create my-robot --template testing --path ~/ftc-projects
|
||||||
|
|
||||||
|
# Preview without creating
|
||||||
|
weevil create my-robot --template testing --dry-run
|
||||||
|
```
|
||||||
|
|
||||||
|
### Variable Substitution
|
||||||
|
|
||||||
|
Templates support variables:
|
||||||
|
|
||||||
|
| 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}};
|
||||||
|
```
|
||||||
|
|
||||||
|
Becomes:
|
||||||
|
```java
|
||||||
|
// Generated by Weevil 1.1.0 on 2026-02-02T10:30:00Z
|
||||||
|
package robot.myrobot;
|
||||||
|
```
|
||||||
|
|
||||||
|
### Success Output
|
||||||
|
|
||||||
|
```
|
||||||
|
✓ Created FTC project 'my-robot' using template 'testing'
|
||||||
|
|
||||||
|
Next steps:
|
||||||
|
cd my-robot
|
||||||
|
weevil test # Run 45 tests (< 2 seconds)
|
||||||
|
weevil build # Build APK
|
||||||
|
weevil deploy # Deploy to robot
|
||||||
|
|
||||||
|
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
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Part 2: `weevil add` Command
|
||||||
|
|
||||||
|
### Overview
|
||||||
|
|
||||||
|
**Purpose:** Add components to existing projects
|
||||||
|
|
||||||
|
**Version:** v1.2.0
|
||||||
|
**Priority:** MEDIUM-HIGH
|
||||||
|
|
||||||
|
### 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
|
||||||
|
|
||||||
|
# Add specific variant
|
||||||
|
weevil add nexus/hardware/dc-motor/core
|
||||||
|
weevil add nexus/hardware/dc-motor/mock
|
||||||
|
|
||||||
|
# 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
|
||||||
|
[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
|
||||||
|
|
||||||
|
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
|
||||||
|
|
||||||
|
**Structure:**
|
||||||
|
```
|
||||||
|
packages.nxgit.dev/
|
||||||
|
├── index.json
|
||||||
|
├── nexus/
|
||||||
|
│ ├── hardware/
|
||||||
|
│ │ ├── dc-motor/
|
||||||
|
│ │ │ ├── package.toml
|
||||||
|
│ │ │ ├── core.tar.gz
|
||||||
|
│ │ │ ├── mock.tar.gz
|
||||||
|
│ │ │ └── complete.tar.gz
|
||||||
|
│ │ └── distance/...
|
||||||
|
│ └── subsystems/...
|
||||||
|
└── 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
|
||||||
|
|
||||||
|
### `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
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 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)
|
||||||
|
|
||||||
|
**`weevil create` command:**
|
||||||
|
- [ ] Template storage system
|
||||||
|
- [ ] Variable substitution
|
||||||
|
- [ ] Basic template
|
||||||
|
- [ ] Testing template
|
||||||
|
- [ ] Git initialization
|
||||||
|
- [ ] Success/error messages
|
||||||
|
- [ ] Documentation
|
||||||
|
- [ ] Tests
|
||||||
|
|
||||||
|
### Phase 2: v1.2.0 (2-3 weeks)
|
||||||
|
|
||||||
|
**`weevil add` command:**
|
||||||
|
- [ ] Package registry setup
|
||||||
|
- [ ] Package manifest format
|
||||||
|
- [ ] Dependency resolver
|
||||||
|
- [ ] Conflict detection
|
||||||
|
- [ ] File installation
|
||||||
|
- [ ] Remove command
|
||||||
|
- [ ] Search command
|
||||||
|
- [ ] List command
|
||||||
|
- [ ] 10+ launch packages
|
||||||
|
- [ ] Documentation
|
||||||
|
- [ ] 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
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Package Quality Standards
|
||||||
|
|
||||||
|
**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
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Future Enhancements
|
||||||
|
|
||||||
|
### v1.3.0+
|
||||||
|
- Package signing (GPG)
|
||||||
|
- Private registries
|
||||||
|
- `weevil publish` command
|
||||||
|
- Package mirrors
|
||||||
|
- Offline mode
|
||||||
|
|
||||||
|
### 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?
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 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: Complete Examples
|
||||||
|
|
||||||
|
### 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
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
*End of Specification*
|
||||||
|
|
||||||
|
**Status:** Ready for Implementation
|
||||||
|
**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
|
||||||
|
|
||||||
|
**Contact:** eric@intrepidfusion.com
|
||||||
|
**Organization:** Nexus Workshops LLC
|
||||||
Reference in New Issue
Block a user