FTC-Project-Gen/DEVELOPER.md

# Developer Documentation

## Project Structure

```
ftc-project-gen-1.0.0-beta/
├── ftc-new-project              # Main entry point (Linux/macOS)
├── ftc-new-project.bat          # Main entry point (Windows)
├── VERSION                      # Version file (1.0.0-beta)
├── README.md                    # User documentation
├── CHANGELOG.md                 # Version history
├── DEVELOPER.md                 # This file
│
├── linux/                       # Linux-specific implementation
│   ├── lib.sh                   # Shared library functions
│   └── templates/               # File templates
│       ├── *.java               # Java source templates
│       ├── *.kts                # Gradle Kotlin scripts
│       ├── *.template           # Templates with placeholders
│       └── *.sh                 # Helper scripts
│
├── windows/                     # Windows-specific implementation
│   ├── lib.bat                  # Shared library functions
│   └── templates/               # File templates (mirrors Linux)
│
└── tests/                       # Test suite
    ├── run-tests.sh             # Test runner
    ├── unit/                    # Unit tests
    └── system/                  # System/integration tests
```

## Architecture

### Template System

Templates are stored in `linux/templates/` and `windows/templates/`. They come in two types:

1. **Static templates**: Direct copies (e.g., Pose2d.java, Drive.java)
2. **Parameterized templates**: Use placeholders (e.g., settings.gradle.kts.template)

**Supported Placeholders:**
- `{{PROJECT_NAME}}` - Name of the project
- `{{SDK_DIR}}` - Path to FTC SDK
- `{{FTC_VERSION}}` - FTC SDK version tag
- `{{GENERATOR_VERSION}}` - Generator version

### Library Functions (lib.sh)

**Key Functions:**
- `get_generator_version()` - Read VERSION file
- `process_template(input, output)` - Replace placeholders
- `copy_template(src, dest)` - Direct file copy
- `create_project_structure(dir)` - Make directories
- `install_templates(project_dir, template_dir)` - Copy all templates
- `create_deploy_script(dir)` - Generate deployment script
- `setup_gradle_wrapper(dir)` - Configure Gradle
- `is_generator_project(dir)` - Check if dir is generator project
- `get_project_generator_version(dir)` - Read project version
- `upgrade_project(dir, template_dir)` - Upgrade infrastructure files
- `init_git_repo(dir)` - Initialize git
- `check_prerequisites()` - Validate environment

### Main Script Flow

1. Parse command-line arguments
2. Load library functions
3. Export environment variables for templates
4. Handle upgrade mode (if `--upgrade` flag)
5. Check if project exists (error if not upgrading)
6. Check prerequisites (git, java, gradle)
7. Setup/verify FTC SDK
8. Create project structure
9. Install templates
10. Setup Gradle wrapper
11. Initialize git repository
12. Display success message

### Upgrade Process

**What Gets Updated:**
- `build.gradle.kts` - Build configuration
- `settings.gradle.kts` - Gradle settings
- `.gitignore` - Git ignore rules
- `build.sh` / `build.bat` - Build helper script
- `deploy-to-robot.sh` / `deploy-to-robot.bat` - Deploy script
- `.ftc-generator-version` - Version marker

**What's Preserved:**
- All source code in `src/main/java/robot/`
- All tests in `src/test/java/robot/`
- README.md (user may have customized)
- Git history
- Gradle wrapper files

### Testing

**Unit Tests:**
- Template processing correctness
- Version extraction
- Template file existence
- Library function behavior

**System Tests:**
- End-to-end project creation
- Directory structure validation
- File existence checks
- Git repository initialization
- Project builds successfully
- Project tests pass
- Upgrade functionality
- Duplicate detection

**Running Tests:**
```bash
# All tests
./tests/run-tests.sh

# Just unit tests
./tests/run-tests.sh unit

# Just system tests  
./tests/run-tests.sh system
```

## Adding New Features

### Adding a New Template

1. Create the template file in `linux/templates/` and `windows/templates/`
2. If it needs variable substitution, use `.template` extension and add placeholders
3. Update `install_templates()` in `lib.sh` / `lib.bat` to copy it
4. Add test to verify template exists
5. Update documentation

**Example:**
```bash
# Create template
cat > linux/templates/MyFile.java.template << 'EOF'
package robot;

// Generated for project: {{PROJECT_NAME}}
public class MyFile {
    // ...
}
EOF

# Update lib.sh install_templates()
process_template "$template_dir/MyFile.java.template" "src/main/java/robot/MyFile.java"

# Update tests
REQUIRED_TEMPLATES+=("MyFile.java.template")
```

### Adding a New Placeholder

1. Export the variable in main script before template processing
2. Update `process_template()` to include the new placeholder
3. Update documentation
4. Add test to verify replacement works

**Example:**
```bash
# In ftc-new-project
export TEAM_NUMBER="12345"

# In lib.sh process_template()
sed -e "s|{{TEAM_NUMBER}}|${TEAM_NUMBER}|g" \
    ...
```

### Upgrading Template System

If you need to modify what files get upgraded:

1. Update `upgrade_project()` function in `lib.sh` / `lib.bat`
2. Add/remove files from the upgrade list
3. Test with existing projects
4. Update CHANGELOG.md
5. Bump version if breaking change

## Version Management

### Bumping Version

1. Update `VERSION` file
2. Update `CHANGELOG.md` with changes
3. Test thoroughly
4. Tag git release: `git tag -a v1.0.0-beta -m "Release 1.0.0-beta"`
5. Generated projects will use new version

### Version Compatibility

Projects track their generator version in `.ftc-generator-version`. This allows:
- Upgrade detection
- Version-specific upgrade logic (if needed)
- Migration paths between major versions

## Testing Strategy

### Pre-Commit Checklist

- [ ] All templates exist in both `linux/` and `windows/`
- [ ] Run `./tests/run-tests.sh` - all pass
- [ ] Create test project manually
- [ ] Build test project: `./gradlew build`
- [ ] Run test project tests: `./gradlew test`
- [ ] Test upgrade on existing project
- [ ] Update CHANGELOG.md
- [ ] Update VERSION if needed

### Release Checklist

- [ ] All tests pass
- [ ] Manual testing on Linux and Windows
- [ ] Documentation updated
- [ ] CHANGELOG.md current
- [ ] VERSION file bumped
- [ ] Git tag created
- [ ] README.md reflects current features

## Common Issues

### Template Processing

**Problem**: Placeholders not replaced
**Solution**: Make sure variable is exported before `process_template()` call

**Problem**: File not found during template install
**Solution**: Check template exists in `templates/` directory

### Testing

**Problem**: System tests fail with "command not found"
**Solution**: Install prerequisites (git, java, gradle)

**Problem**: Generated project doesn't build
**Solution**: Check Gradle configuration templates are valid

### Cross-Platform

**Problem**: Line endings differ between platforms
**Solution**: Use `.gitattributes` to normalize line endings

**Problem**: Path separators (/ vs \)
**Solution**: Use platform-appropriate functions in lib.sh/lib.bat

## Best Practices

1. **Templates are static**: Keep templates simple, move logic to scripts
2. **Test everything**: Add tests for new features
3. **Document changes**: Update CHANGELOG.md
4. **Version carefully**: Breaking changes require major version bump
5. **Preserve user code**: Never modify user source during upgrade
6. **Cross-platform parity**: Keep Linux and Windows in sync

## Future Improvements

Potential areas for enhancement:

- [ ] More template examples (autonomous, advanced subsystems)
- [ ] Template selection during creation (mecanum vs swerve)
- [ ] Web-based project generator
- [ ] CI/CD integration examples
- [ ] Performance optimization for large projects
- [ ] Plugin system for custom templates
- [ ] Migration tools for older FTC projects

## Contributing

1. Fork the repository
2. Create feature branch
3. Add tests for new features
4. Ensure all tests pass
5. Update documentation
6. Submit pull request

## License

MIT License - See LICENSE file for details.