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:

# 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:

# 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:

# 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.