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

751
docs/ROADMAP.md
View File

@@ -11,17 +11,17 @@ This document outlines the planned feature development for Weevil across multipl
---
## Version 1.1.0 - Core Stability & Team Adoption ✅ COMPLETE
## Version 1.1.0 - Core Stability & Professional Templates ✅ COMPLETE
**Theme:** Making Weevil production-ready for FTC teams with essential operational features and reducing friction in existing workflows.
**Theme:** Making Weevil production-ready for FTC teams with essential operational features, reducing friction in existing workflows, and providing professional code templates for learning.
**Status:** Released as v1.1.0-beta.2 (pending Windows testing)
**Status:** Released as v1.1.0 (all features complete and tested)
### System Audit & Diagnostics ✅
**Feature:** `weevil doctor` command
**Description:** Provides a comprehensive audit of the development environment, showing what's installed and what versions are present. This would display:
**Description:** Provides a comprehensive audit of the development environment, showing what's installed and what versions are present. This displays:
- FTC SDK versions (current and available)
- Android SDK installation status and version
- Gradle version and location
@@ -33,17 +33,6 @@ This document outlines the planned feature development for Weevil across multipl
**Rationale:** Teams need visibility into their environment to troubleshoot issues. Coaches working with multiple machines need to quickly verify setup consistency across laptops. This builds trust by making Weevil's actions transparent.
**Pros:**
- Straightforward to implement - query what `weevil setup` installed
- High value for troubleshooting
- Professional tooling feel
- Helps with team onboarding (new members can verify setup)
**Cons:**
- Need to handle edge cases (partial installations, manual modifications)
- Version detection across platforms may be fragile
- Output formatting needs to be clear for non-technical users
---
### Dependency Cleanup ✅
@@ -60,17 +49,7 @@ Offers options for selective cleanup (e.g., keep SDK but remove Gradle) or compl
**Status:** ✅ Complete - Shipped in v1.1.0
**Rationale:** Teams switch machines, need to free disk space, or want to start fresh. Without a clean uninstall, Weevil leaves artifacts behind. This is critical for maintaining system hygiene and building confidence that Weevil doesn't pollute the environment.
**Pros:**
- Demonstrates respect for users' systems
- Essential for testing and development
- Helps with troubleshooting (clean slate approach)
**Cons:**
- Must track what Weevil installed vs. what user installed manually
- Risk of removing shared dependencies other tools need
- Need careful confirmation prompts to prevent accidental deletion
**Implementation:** `weevil uninstall`, `weevil uninstall --dry-run`, `weevil uninstall --only <N>`
---
@@ -88,20 +67,12 @@ Handle `HTTP_PROXY`, `HTTPS_PROXY`, `NO_PROXY` environment variables and write a
**Status:** ✅ Complete - Shipped in v1.1.0
**Implementation:** `--proxy <url>` and `--no-proxy` global flags, automatic HTTPS_PROXY/HTTP_PROXY env var detection
**Rationale:** Many FTC teams work in schools or corporate environments with mandatory proxy servers. Without proxy support, Weevil is unusable in these environments, cutting off a significant portion of the potential user base.
**Pros:**
- Unlocks enterprise/school environments
- Relatively well-understood problem space
- Shows professionalism and enterprise-readiness
**Cons:**
- Proxy configurations vary widely
- Authentication (proxy username/password) adds complexity
- SSL/certificate issues in corporate environments
- Testing requires access to proxy environments
**Implementation:**
- `--proxy <url>` global flag
- `--no-proxy` global flag (bypass)
- Automatic HTTPS_PROXY/HTTP_PROXY env var detection
- git2/libgit2 proxy support
- Gradle wrapper respects proxy settings
---
@@ -117,25 +88,72 @@ Handle `HTTP_PROXY`, `HTTPS_PROXY`, `NO_PROXY` environment variables and write a
The goal: students work in Android Studio (the tool they know) but get Weevil's improved project structure and deployment workflow behind the scenes.
**Status:** ✅ Complete - Shipped in v1.1.0-beta.2
**Status:** ✅ Complete - Shipped in v1.1.0
**Implementation:** Auto-generated `.idea/` run configurations (Build, Deploy auto/USB/WiFi, Test), workspace.xml for clean file tree, cross-platform support (Unix .sh and Windows .bat variants)
**Implementation:**
- Auto-generated `.idea/` run configurations
- Build
- Deploy (auto) - auto-detects USB/WiFi
- Deploy (USB) - forces USB
- Deploy (WiFi) - forces WiFi
- Test - runs unit tests
- workspace.xml for clean file tree
- Cross-platform support (Unix `.sh` and Windows `.bat` variants)
- One-click deployment from IDE
**Note:** Requires Shell Script plugin installation in Android Studio (documented in README)
**Note:** Requires Shell Script plugin installation in Android Studio (one-time setup, documented in README)
**Rationale:** This is the killer feature that bridges the gap between Weevil's better engineering practices and students' existing workflow. Kids already know Android Studio. Making Weevil "just work" with it removes adoption friction and lets them focus on robot code, not tooling.
---
**Pros:**
- Huge competitive advantage for Nexus Workshops
- Leverages existing student knowledge
- Reduces cognitive load (one less tool to learn)
- Makes Weevil invisible in the best way - it just works
### Template System ✅ **THE GAME CHANGER**
**Cons:**
- Android Studio project file format may change between versions
- Complex to test across different Android Studio versions
- May conflict with students' existing Android Studio customizations
- Requires Shell Script plugin (one-time setup)
**Feature:** Professional code templates for project creation
**Description:** Transform Weevil from "empty project generator" to "start with professional code." Includes:
**Templates:**
1. **`basic`** (default) - Minimal FTC project
- Clean starting point
- ~10 files, ~50 lines of code
- Perfect for teams starting from scratch
2. **`testing`** - Professional testing showcase
- **45 comprehensive tests** that pass in < 2 seconds
- **3 complete subsystems** (MotorCycler, WallApproach, TurnController)
- **Hardware abstraction layer** with interfaces and mocks
- **Professional documentation** (6 markdown files, ~65 KB)
- ~30 files, ~2,500 lines of code
- Real patterns used in competition
**Commands:**
- `weevil new <name>` - Creates project with basic template
- `weevil new <name> --template testing` - Creates with testing showcase
- `weevil new --list-templates` - Shows available templates with details
**Status:** ✅ Complete - Shipped in v1.1.0
**Implementation:**
- Templates embedded in binary using `include_dir!` macro
- Variable substitution (`{{PROJECT_NAME}}`, `{{PACKAGE_NAME}}`, `{{CREATION_DATE}}`, `{{WEEVIL_VERSION}}`, `{{TEMPLATE_NAME}}`)
- Template validation with helpful error messages
- Templates overlay on ProjectBuilder infrastructure
- 62 comprehensive tests (all passing)
**Rationale:** **This is revolutionary for FTC.** Most teams start with empty projects and learn by trial-and-error on hardware. Now they can:
- Start with working, tested code
- Run 45 tests instantly on their PC
- Learn from professional patterns
- Modify working examples for their robot
- Understand test-driven development
This is the kind of code students would write if they had years of experience. Now they can START with it.
**Impact:**
- Teams learn professional software engineering patterns
- Testing without hardware (save hours of deploy time)
- Clean architecture examples (interfaces, mocks, state machines)
- Comprehensive documentation showing WHY and HOW
- Positions Nexus Workshops as FTC software authority
---
@@ -143,63 +161,132 @@ The goal: students work in Android Studio (the tool they know) but get Weevil's
**Feature:** Comprehensive manual setup documentation
**Description:** Detailed, step-by-step instructions for manually installing every dependency when automation fails. This includes:
- Screenshots or terminal output examples
- Platform-specific variations (Windows vs. Linux)
- Common error messages and solutions
- Checksums for verifying downloads
- Fallback download URLs if primary sources are blocked
**Description:** Detailed, step-by-step instructions for manually installing every dependency when automation fails.
**Status:** 🔄 Deferred to v1.2.0 - Basic troubleshooting exists in README, comprehensive guide pending
**Rationale:** Automation fails. Proxies block downloads. Firewalls interfere. Having a "guaranteed to work" manual path builds confidence and ensures teams aren't stuck. This is about providing an escape hatch and building trust.
**Pros:**
- Low effort (documentation, not code)
- High value when automation fails
- Educational - teaches students what's happening under the hood
- Demonstrates thoroughness and professionalism
**Cons:**
- Requires maintenance as dependencies evolve
- Screenshots go stale quickly
- Platform variations multiply documentation burden
---
### Package Distribution (Debian/Ubuntu) 🔄
**Feature:** `.deb` package for easy installation on Debian-based systems
**Description:** Create Debian packages that can be installed via `sudo dpkg -i weevil_1.1.0_amd64.deb` or distributed through a personal APT repository. Package would:
- Install weevil binary to `/usr/bin`
- Include man pages and documentation
- Handle any system dependencies
- Support clean uninstallation
**Status:** 🔄 Deferred - Not essential for initial adoption
**Rationale:** Provides a "professional" distribution method for Linux users. Makes Weevil feel like real software, not just a script. Easier for schools/teams to deploy across multiple machines.
**Pros:**
- Professional appearance
- Standard Linux distribution method
- Can include in deployment automation (Ansible, etc.)
- `cargo-deb` makes this relatively easy
**Cons:**
- Maintenance overhead for packaging
- Need to support multiple Ubuntu/Debian versions
- Most teams will just download the binary anyway
- Not essential for functionality
---
## Version 1.2.0 - Polish & Accessibility
## Version 1.2.0 - Package Ecosystem 🔥
**Theme:** Making Weevil accessible to non-technical users and expanding platform support.
**Theme:** Transforming Weevil from project generator to ecosystem platform. Teams can extend projects with community-shared components.
**Status:** Planning
**Status:** Planning - Expected Q2 2026
### `weevil add` - Component Package Manager ⚠️ **THE NEXT BIG THING**
**Feature:** Package manager for sharing and reusing FTC robot code components
**Description:** Enable teams to add pre-built components to existing projects:
```bash
# Add a complete subsystem
weevil add nexus/subsystems/mecanum-drive/complete
# Add just the interface
weevil add nexus/hardware/dc-motor/core
# Add test mocks
weevil add nexus/hardware/dc-motor/mock --dev
# Search for packages
weevil search "mecanum"
# See what's installed
weevil list --installed
# Update packages
weevil update
```
**Package Naming:** `scope/category/name/variant`
**Examples:**
- `nexus/hardware/dc-motor/complete` - Motor controller (interface + FTC impl + mocks + examples)
- `nexus/subsystems/wall-approach/complete` - Complete wall approach subsystem
- `nexus/examples/autonomous/simple-auto` - Example autonomous routine
- `team1234/sensors/custom-lidar/core` - Community package from Team 1234
**Standard Variants:**
- `core` - Interface + FTC implementation
- `mock` - Test doubles for unit testing
- `example` - Example OpMode showing usage
- `complete` - All of the above
**Key Features:**
- **Dependency resolution** - Auto-install dependencies (e.g., subsystem → hardware interfaces)
- **Conflict handling** - Interactive, force, or skip modes
- **Version management** - Semantic versioning, upgrade tracking
- **License compliance** - Track and display licenses
- **Quality tiers:**
- **Community** - Open submissions
- **Nexus Verified** - Reviewed, tested, maintained by Nexus Workshops
**Rationale:** This is the network effect feature that creates a moat:
- **For Teams:** Stop reinventing wheels, use proven solutions
- **For Nexus Workshops:** Becomes central hub for FTC software knowledge
- **For Community:** Share solutions, build on each other's work
- **For FTC:** Raises software quality across all teams
**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`
**Supporting Commands:**
- `weevil remove <package>` - Remove installed package
- `weevil search <query>` - Search package registry
- `weevil list [--installed|--available]` - List packages
- `weevil info <package>` - Show package details
- `weevil update [package]` - Update packages
**Package Repository:** https://packages.nxgit.dev (to be created)
**Status:** ⚠️ In Planning - Design complete, implementation starting
**Priority:** **CRITICAL** - This is the strategic differentiator for v1.2.0
**Estimated Effort:** 2-3 weeks development + 1 week for initial package set
**Success Metrics:**
- 20+ quality packages at launch
- 100+ package downloads in first month
- 5+ community-contributed packages within 3 months
- Active package ecosystem by end of 2026
---
### Windows Testing & Stabilization ✅
**Feature:** Complete Windows support verification
**Status:** ✅ Complete - All 62 tests passing on Windows, proxy support working, Android Studio integration verified
---
### Android Studio Debugging Support
@@ -212,54 +299,9 @@ The goal: students work in Android Studio (the tool they know) but get Weevil's
- Handle ADB debugging bridge setup automatically
- Support both USB and WiFi debugging
Students should be able to:
1. Set breakpoints in their OpMode code
2. Select "Debug" configuration from Android Studio
3. Click the debug button (🐛)
4. Have the debugger attach to the running robot
5. Step through code, inspect variables, etc.
**Status:** 🔄 Deferred to v1.3.0 - Advanced feature, build basic package system first
**Rationale:** Debugging is a critical skill, and print-statement debugging (`telemetry.addData()`) is primitive. Teaching students to use a real debugger makes them better engineers. This feature positions Weevil as a complete development environment, not just a build tool.
**Pros:**
- Massive educational value - teaches proper debugging
- Competitive advantage (official SDK doesn't make this easy)
- Natural extension of existing Android Studio integration
- Students already familiar with debuggers from other IDEs
**Cons:**
- Android debugging setup is complex (ADB, JDWP, remote attach)
- WiFi debugging is finicky and may be unreliable
- Debugging autonomous modes has timing implications
- Requires deep understanding of Android debug protocol
- May not work reliably on all Control Hub firmware versions
**Priority:** HIGH - Natural next step after basic Android Studio integration
**Technical Notes:**
- Need to generate Android Studio remote debug configurations
- May require modifications to deploy scripts to enable debug mode
- JDWP (Java Debug Wire Protocol) over ADB
- Consider "Debug (USB)" and "Debug (WiFi)" separate configurations
---
### Windows Testing & Stabilization
**Feature:** Complete Windows support verification
**Description:** Comprehensive testing of all v1.1.0 features on Windows 10 and Windows 11:
- Proxy support with Windows-specific quirks
- Android Studio integration with Windows paths
- Build and deployment scripts (`.bat` files)
- Gradle wrapper on Windows
- Path handling (backslashes vs. forward slashes)
**Status:** Required before v1.1.0 final release
**Rationale:** Many FTC teams use Windows. Can't ship v1.1.0 final without Windows verification.
**Priority:** CRITICAL - Blocks v1.1.0 final release
**Priority:** MEDIUM-HIGH - Natural extension after package system
---
@@ -274,21 +316,7 @@ Students should be able to:
- Appears in "Programs and Features" for clean uninstall
- Optionally creates desktop shortcut
**Status:** Planned for v1.2.0
**Rationale:** Windows users expect installers, not loose executables. An MSI makes Weevil feel professional and legitimate. Start menu integration makes it discoverable.
**Pros:**
- Expected Windows UX
- Automatic PATH configuration (users don't need to understand this)
- Professional appearance
- Easy deployment in school environments
**Cons:**
- MSI creation and signing has complexity
- Code signing certificates cost money ($200+/year)
- Without code signing, Windows shows security warnings
- Testing across Windows versions (10, 11)
**Status:** 🔄 Deferred to v1.2.0
**Priority:** MEDIUM - Polish feature for Windows adoption
@@ -298,21 +326,9 @@ Students should be able to:
**Feature:** Desktop file and menu integration for Linux
**Description:** Include `.desktop` files and icon assets that integrate with Linux desktop environments (GNOME, KDE, XFCE). This makes Weevil appear in application menus and launchers. Likely bundled with the .deb package.
**Status:** 🔄 Deferred to v1.2.0
**Rationale:** Makes Weevil discoverable in the GUI for users who aren't comfortable with terminals. Fits the "reduce cognitive load" philosophy.
**Pros:**
- Low effort (just create .desktop files)
- Helps GUI users discover Weevil
- Standard Linux desktop integration
**Cons:**
- Different desktop environments have quirks
- Icon design needed
- Only useful if there's a GUI to launch
**Priority:** MEDIUM - Pairs well with GUI development
**Priority:** MEDIUM - Pairs well with GUI development (v1.3.0+)
---
@@ -320,28 +336,32 @@ Students should be able to:
**Feature:** Support for Arch, Fedora, Slackware, and other distributions
**Description:** Adapt installation scripts to detect and use different package managers:
- Arch: pacman
- Fedora: dnf/yum
- Slackware: pkgtool
- Generic: compile from source instructions
**Status:** 🔄 Deferred - Low priority, most teams use Ubuntu/Debian or Windows
May also include packaging for AUR (Arch User Repository), Fedora Copr, etc.
**Priority:** LOW-MEDIUM
**Rationale:** Expands addressable market. Some teams use Arch or Fedora. Shows commitment to Linux ecosystem.
---
**Pros:**
- Broader Linux support
- Community contributions likely (Arch users love AUR packages)
- Demonstrates technical depth
## Version 1.3.0 - Developer Experience
**Cons:**
- Significant testing burden across distros
- Each package manager has different quirks
- Low ROI - most teams use Ubuntu/Debian or Windows
- Maintenance overhead
**Theme:** Making Weevil an all-in-one development environment with advanced debugging and UX polish
**Priority:** LOW-MEDIUM - Nice to have, but niche
**Status:** Planning - Expected Q3 2026
### Android Studio Debugging Support
**Feature:** Full debugging integration for Android Studio
**Description:** Students should be able to:
1. Set breakpoints in their OpMode code
2. Select "Debug" configuration from Android Studio
3. Click the debug button (🐛)
4. Have the debugger attach to the running robot
5. Step through code, inspect variables, etc.
**Status:** Planned for v1.3.0
**Priority:** HIGH - Natural next step after package ecosystem
---
@@ -349,38 +369,18 @@ May also include packaging for AUR (Arch User Repository), Fedora Copr, etc.
**Feature:** GUI application for teams uncomfortable with terminals
**Description:** A graphical interface that wraps Weevil's functionality, allowing users to:
- Create new projects through forms/wizards
- Configure project settings visually
- Run builds and deployments with buttons
- View status and logs in a window
- Manage dependencies through checkboxes/dropdowns
**Description:** A graphical interface that wraps Weevil's functionality:
- Create projects through forms/wizards
- Visual project configuration
- Button-based builds and deployments
- Visual package browser and installer
- Status and logs in a window
**Technical Approaches:**
1. **Tauri** - Rust + web frontend (HTML/CSS/JS), native performance, small binary
2. **Local web server** - Weevil serves HTML, opens browser automatically
3. **Native GUI** - GTK, Qt, or egui (Rust native GUI)
**Technical Approach:** Tauri (Rust + web frontend) for native performance and small binary
**Rationale:** Reduces barrier to entry for students and coaches unfamiliar with terminals. Lowers cognitive load - students focus on robotics, not command syntax. Particularly valuable for younger teams or schools with limited technical resources.
**Status:** Planned for v1.3.0
**Pros:**
- Significantly lowers barrier to entry
- Appeals to visual learners
- Makes Weevil accessible to non-programmers (coaches, parents)
- Could include visual project templates/wizards
- Positions Weevil as "real software" vs. "developer tool"
**Cons:**
- Substantial development effort
- GUI framework choice has long-term implications
- Need to maintain two interfaces (CLI + GUI)
- UI design and UX is its own skillset
- Testing GUI across platforms is complex
- May need separate binary or flag to launch GUI
**Priority:** MEDIUM-HIGH - Valuable for adoption, but requires careful planning
**Dependencies:** If building a GUI, having an API layer (see below) makes sense for architecture.
**Priority:** MEDIUM-HIGH - Lowers barrier to entry significantly
---
@@ -389,114 +389,37 @@ May also include packaging for AUR (Arch User Repository), Fedora Copr, etc.
**Feature:** Internal API that both CLI and GUI can consume
**Description:** Refactor Weevil's core functionality behind a REST API:
- API could run as a local server or be embedded
- CLI becomes a thin client to the API
- GUI uses the same API endpoints
- Enables future integrations (VS Code extension, web dashboard, etc.)
- CLI becomes thin client
- GUI uses same API endpoints
- Enables future integrations (VS Code extension, web dashboard)
Endpoints might include:
- `POST /project/create` - Create new project
- `GET /status` - System audit
- `POST /build` - Trigger build
- `GET /dependencies` - List installed dependencies
- etc.
**Status:** 🔄 Deferred - Only if building GUI
**Rationale:** Clean separation of concerns. Makes adding new interfaces (GUI, IDE plugins) easier. Enables potential future features like remote builds or team collaboration.
**Pros:**
- Clean architecture
- Multiple frontends share same backend logic
- Easier testing (API can be tested independently)
- Opens door to remote/distributed features
- Could enable web-based dashboard for teams
**Cons:**
- Significant refactoring of existing code
- Adds complexity (serialization, HTTP layer, error handling)
- Local-only API doesn't provide much value initially
- May be over-engineering for current needs
- gRPC/Protobuf would be overkill unless remote features needed
**Priority:** LOW-MEDIUM - Nice architecture, but not essential unless building GUI or extensions
**Note:** If staying local-only, CLI calling library functions directly is simpler. Only build API if there's a concrete need (GUI, remote features, integrations).
**Priority:** MEDIUM - Clean architecture, but not essential unless building GUI
---
## Version 1.3.0 - Extended Platform Support
## Version 1.4.0 - Advanced Tooling
(Features carried over from v1.2.0 if not completed, plus any new platform-specific enhancements)
**Theme:** Making Weevil an intelligent development assistant
---
**Status:** Planning - Expected Q4 2026
## Version 1.4.0 - Ecosystem & Package Management
### Troubleshooting Suite
**Theme:** Transforming Weevil from a project generator into an ecosystem platform. This is where Weevil becomes more than what Android Studio offers.
**Feature:** Comprehensive diagnostic and debugging tools
### FTC Component Package Manager
**Potential Components:**
1. **Connectivity Diagnostics** - `weevil diagnose adb`
2. **Build Analysis** - Parse build errors and suggest fixes
3. **Log Analysis** - `weevil logs analyze`
4. **Performance Profiling** - Measure loop times, identify bottlenecks
5. **Code Quality Checks** - Static analysis, anti-pattern detection
6. **Interactive Troubleshooter** - Wizard-style troubleshooting
**Feature:** Package manager for sharing and reusing FTC robot code components
**Status:** Planned for v1.4.0
**Description:** Enable teams to publish and consume reusable robot code components. Examples:
- Mechanim wheel controllers
- Sensor abstractions
- Autonomous routines
- Vision processing pipelines
- Hardware wrappers
**Potential Approaches:**
1. **Git Submodule Style (FreeBSD Ports):**
- Package index is a Git repository with manifests
- `weevil add mechanim-wheel` pulls code via Git into project
- Code is vendored locally, teams can modify
- Clean version control story
2. **Central Registry:**
- Nexus Workshops hosts package registry at nxgit.dev
- Teams publish packages with metadata (license, dependencies, version)
- `weevil search wheels` finds packages
- `weevil add team123/mechanim-wheel` installs
- Binary or source distribution
3. **Hybrid Approach:**
- Decentralized (anyone can host packages on Git)
- Nexus Workshops provides discovery/curation (searchable index)
- Teams can specify direct Git URLs or use curated registry
**Key Considerations:**
- **Licensing:** Must track and display licenses, ensure compliance
- **Namespacing:** Avoid collisions (team number prefixes? org namespaces?)
- **Versioning:** Semantic versioning, dependency resolution
- **Quality:** Curated vs. open submission, review process
- **Trust:** Code signing? Verified publishers?
**Rationale:** This is the network effect feature. Teams contribute back proven solutions. Nexus Workshops becomes the central hub for FTC software engineering knowledge. Competitive moat - no other tool offers this. Transforms FTC from "everyone reinvents wheels" to "community shares solutions."
**Pros:**
- Massive competitive differentiation
- Creates community around Weevil/Nexus Workshops
- Direct value to teams (stop reinventing proven solutions)
- Positions Nexus Workshops as FTC software authority
- Revenue potential (premium packages? consulting on custom components?)
- Network effects - more users = more packages = more value
**Cons:**
- Complex to implement correctly
- Licensing compliance is non-trivial
- Moderation/curation burden (prevent malicious code)
- Version conflicts and dependency hell
- Need critical mass of packages to be valuable
- Support burden (teams will ask for help with downloaded packages)
- Security concerns (code execution from third parties)
**Priority:** HIGH - This is the strategic differentiator for v1.4.0
**Success Criteria:**
- At least 10 high-quality packages at launch
- Clear licensing and attribution
- Simple `weevil add` and `weevil remove` workflow
- Nexus Workshops positions as curator/quality gatekeeper
**Priority:** MEDIUM-HIGH - High value but complex
---
@@ -508,29 +431,9 @@ Endpoints might include:
**Feature:** Support for C++ FTC projects alongside Java
**Description:** If/when FTC officially supports C++ for robot programming, Weevil should support creating and managing C++ projects:
- C++ project templates
- Build system integration (CMake? Gradle?)
- Android NDK integration
- Debugging support
- Mixed Java/C++ projects (JNI bridges)
**Status:** Research - Contingent on FTC officially supporting C++
**Rationale:** Stay ahead of FTC changes. C++ may offer performance benefits for vision processing or complex algorithms. Supporting multiple languages positions Weevil as the universal FTC development tool.
**Pros:**
- Future-proofing
- Potential performance benefits for teams
- Differentiator if other tools don't support C++
- Demonstrates technical sophistication
**Cons:**
- Uncertain if FTC will actually support C++
- C++ toolchain complexity (NDK, build systems)
- Most teams won't need/want C++
- Significant development effort
- Testing burden (two language stacks)
**Priority:** LOW - Wait and see if FTC actually supports C++
**Priority:** LOW - Wait for FTC announcement
**Trigger:** FTC officially announces C++ support
@@ -540,88 +443,9 @@ Endpoints might include:
**Feature:** Plugin-based language support architecture
**Description:** If supporting multiple languages (Java, C++, potentially Kotlin), refactor Weevil to have a language-agnostic core with language-specific plugins:
- Core: project structure, build orchestration, deployment
- Plugins: language-specific templates, build rules, dependencies
**Status:** Research - Only if supporting 3+ languages
This makes adding new languages easier and keeps core clean.
**Rationale:** Clean architecture for extensibility. Easier to maintain than language-specific code scattered throughout.
**Pros:**
- Cleaner codebase
- Community could contribute language plugins
- Future-proof for whatever FTC supports next
**Cons:**
- Significant refactoring
- May be over-engineering if only supporting Java + maybe C++
- Plugin API needs careful design
**Priority:** LOW-MEDIUM - Only if supporting 3+ languages
---
## Version 1.6.0+ - Advanced Tooling
**Theme:** Making Weevil an all-in-one development environment
### Troubleshooting Suite
**Feature:** Comprehensive diagnostic and debugging tools
**Description:** A suite of troubleshooting tools that help teams diagnose common problems:
**Potential Components:**
1. **Connectivity Diagnostics:**
- `weevil diagnose adb` - Check ADB connection to robot controller
- Detect USB vs. WiFi connection issues
- Test latency and connection stability
2. **Build Analysis:**
- Parse build errors and suggest fixes
- Detect common misconfigurations (wrong SDK version, missing dependencies)
- Gradle build cache issues
3. **Log Analysis:**
- `weevil logs analyze` - Parse robot logs for common errors
- Highlight crashes, exceptions, performance issues
- Suggest fixes based on error patterns
4. **Performance Profiling:**
- Measure loop times
- Identify performance bottlenecks in autonomous
- Memory usage analysis
5. **Code Quality Checks:**
- Static analysis for common mistakes
- Style guide compliance
- Anti-pattern detection (blocking operations in main loop, etc.)
6. **Interactive Troubleshooter:**
- Wizard-style troubleshooting ("What problem are you having?")
- Step-by-step guidance
- Link to documentation/solutions
**Rationale:** This is a game-changer for teams without experienced mentors. Most FTC teams struggle with debugging. Automated troubleshooting reduces frustration and keeps teams moving. Positions Nexus Workshops as the support resource.
**Pros:**
- High value - debugging is painful for teams
- Competitive advantage (no other tool offers this)
- Reduces support burden (self-service troubleshooting)
- Educational - teaches debugging skills
- Could integrate with package manager (suggest better packages)
**Cons:**
- Requires deep knowledge of common FTC issues
- Error pattern recognition is complex
- May give wrong advice (false positives)
- Maintenance as FTC SDK evolves
- Difficult to test comprehensively
**Priority:** MEDIUM-HIGH - Valuable but complex, needs careful design
**Implementation Note:** Could start simple (common error pattern matching) and evolve based on real team issues encountered through Nexus Workshops.
**Priority:** LOW-MEDIUM
---
@@ -646,37 +470,17 @@ This makes adding new languages easier and keeps core clean.
**Feature:** Support for SOCKS4/SOCKS5 proxies in addition to HTTP proxies
**Description:** Extend proxy support to handle SOCKS proxies, which are common in certain corporate and academic environments:
- Auto-detect SOCKS proxy from environment variables
- Support SOCKS4, SOCKS5, and SOCKS5h protocols
- Handle authentication if required
- Configure all network operations (Gradle, SDK downloads, Git) to use SOCKS
**Status:** Research - needs market validation
**Rationale:** Some environments use SOCKS proxies instead of HTTP proxies. While HTTP proxy support covers most cases, SOCKS support would enable Weevil in additional restricted environments.
**Pros:**
- Broader environment support
- Some corporate networks mandate SOCKS
- Demonstrates thoroughness
**Cons:**
- More complex than HTTP proxy (different protocols)
- Smaller user base than HTTP proxy
- Not all tools (Gradle, Git) support SOCKS equally well
- May require native library integration (e.g., libcurl with SOCKS support)
- Authentication adds complexity
**Priority:** LOW - HTTP proxy covers most use cases
**Decision Point:** Wait for user requests. If teams need SOCKS support, prioritize accordingly.
**Decision Point:** Wait for user requests
---
### Cloud Build Services
**Description:** Remote build servers for teams with slow computers. Teams push code, Weevil builds in the cloud, streams back APK.
**Description:** Remote build servers for teams with slow computers
**Status:** Research - needs cost/benefit analysis, infrastructure planning
@@ -684,7 +488,7 @@ This makes adding new languages easier and keeps core clean.
### VS Code Extension
**Description:** Extension for VS Code to provide similar integration as Android Studio.
**Description:** Extension for VS Code to provide similar integration as Android Studio
**Status:** Research - depends on VS Code adoption in FTC community
@@ -692,15 +496,15 @@ This makes adding new languages easier and keeps core clean.
### Team Collaboration Features
**Description:** Features for teams to coordinate across multiple developers - shared configurations, code review integration, task tracking.
**Description:** Features for teams to coordinate across multiple developers
**Status:** Research - needs market validation (do teams want this?)
**Status:** Research - needs market validation
---
### Custom Hardware Support
**Description:** Templates and tools for teams using custom sensors or actuators beyond standard FTC parts.
**Description:** Templates and tools for teams using custom sensors or actuators
**Status:** Research - depends on community need
@@ -720,11 +524,58 @@ The `weevil upgrade` command is designed to migrate projects forward across vers
How we'll measure if Weevil is succeeding:
### v1.1.0 Metrics (Achieved)
- ✅ 62 comprehensive tests, all passing
- ✅ Zero compiler warnings
- ✅ Cross-platform support (Windows, Linux, macOS)
- ✅ Professional documentation (README, DESIGN_AND_TEST_PLAN, etc.)
- ✅ Testing template with 45 passing tests
### v1.2.0 Target Metrics
- 20+ quality packages at launch
- 100+ package downloads in first month
- 5+ community-contributed packages within 3 months
- 50+ teams using Weevil
### Long-term Metrics
- **Adoption:** Number of teams using Weevil (tracked via downloads, GitHub stars)
- **Retention:** Teams continuing to use across seasons
- **Nexus Workshops impact:** Does Weevil drive workshop signups or consulting engagement?
- **Nexus Workshops impact:** Weevil drives workshop signups or consulting engagement
- **Community:** Package contributions, GitHub issues/PRs, community discussions
- **Competitive outcomes:** Do Nexus Workshops teams using Weevil perform better?
- **Competitive outcomes:** Nexus Workshops teams using Weevil perform better
---
## Recent Accomplishments (v1.1.0)
**What We Shipped:**
1. **Template System** - Start with professional code, not empty files
- 45-test testing showcase
- 3 complete subsystems
- Hardware abstraction patterns
- Professional documentation
2. **Android Studio Integration** - One-click deployment from IDE
- Auto-generated run configurations
- Clean file tree
- Cross-platform support
3. **Proxy Support** - Works in corporate/school environments
- HTTP/HTTPS proxy support
- Environment variable detection
- Bypass capability
4. **System Diagnostics** - `weevil doctor` and `weevil uninstall`
- Comprehensive environment audit
- Selective component removal
- Troubleshooting support
**Impact:**
- Teams can now learn from professional code instead of starting from scratch
- Testing without hardware saves hours of development time
- Corporate/school adoption enabled
- Professional-grade tooling for FTC
---
@@ -738,6 +589,14 @@ This roadmap is subject to change based on:
Features may be accelerated, deferred, or cancelled as the project evolves.
**Want to influence the roadmap?**
- Submit GitHub issues with feature requests
- Share your team's pain points
- Contribute to package ecosystem (v1.2.0+)
- Provide feedback on template quality
---
*Last Updated: February 2026*
*Last Updated: February 2026*
*Current Release: v1.1.0*
*Next Release: v1.2.0 (Package Ecosystem) - Q2 2026*