Skip to content

Commit 14b40ae

Browse files
Rlin1027claude
Rlin1027
and
claude
committed
feat: Phase 3 Beta Launch — README, CI/CD, contributing guide, version 0.2.0
- Comprehensive README with usage examples, command reference, custom rules guide - GitHub Actions CI (Python 3.10-3.13 matrix, ruff, mypy) and release workflow - CONTRIBUTING.md with development setup and contribution guidelines - CHANGELOG.md following Keep a Changelog format - Version bump 0.1.0 → 0.2.0, classifier Alpha → Beta Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
1 parent 0a32183 commit 14b40ae

File tree

8 files changed

+374
-9
lines changed

8 files changed

+374
-9
lines changed

‎.github/workflows/ci.yml‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
name: CI
2+
3+
on:
4+
push:
5+
branches: [main]
6+
pull_request:
7+
branches: [main]
8+
9+
jobs:
10+
test:
11+
runs-on: ubuntu-latest
12+
strategy:
13+
matrix:
14+
python-version: ["3.10", "3.11", "3.12", "3.13"]
15+
steps:
16+
- uses: actions/checkout@v4
17+
- name: Set up Python ${{ matrix.python-version }}
18+
uses: actions/setup-python@v5
19+
with:
20+
python-version: ${{ matrix.python-version }}
21+
- name: Install dependencies
22+
run: pip install -e ".[dev]"
23+
- name: Run tests
24+
run: pytest tests/ -q --tb=short
25+
26+
lint:
27+
runs-on: ubuntu-latest
28+
steps:
29+
- uses: actions/checkout@v4
30+
- uses: actions/setup-python@v5
31+
with:
32+
python-version: "3.12"
33+
- run: pip install -e ".[dev]"
34+
- name: Ruff check
35+
run: ruff check src/ tests/
36+
- name: Ruff format check
37+
run: ruff format --check src/ tests/
38+
- name: Mypy
39+
run: mypy src/rosforge/ --ignore-missing-imports

‎.github/workflows/release.yml‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
name: Release
2+
3+
on:
4+
release:
5+
types: [published]
6+
7+
jobs:
8+
publish:
9+
runs-on: ubuntu-latest
10+
permissions:
11+
id-token: write
12+
steps:
13+
- uses: actions/checkout@v4
14+
- uses: actions/setup-python@v5
15+
with:
16+
python-version: "3.12"
17+
- name: Install build tools
18+
run: pip install build
19+
- name: Build package
20+
run: python -m build
21+
- name: Publish to PyPI
22+
uses: pypa/gh-action-pypi-publish@release/v1

‎CHANGELOG.md‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
# Changelog
2+
3+
All notable changes to ROSForge will be documented in this file.
4+
5+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
6+
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7+
8+
## [0.2.0] - 2026-02-24
9+
10+
### Added
11+
- Auto build verification and fix loop (`--max-fix-attempts`)
12+
- Interactive migration mode (`--interactive`)
13+
- Batch workspace migration (`rosforge migrate-workspace`)
14+
- Custom transformation rules via YAML (`--rules`)
15+
- Cost estimation display before migration
16+
- Confidence scoring in CLI output
17+
- Pre-migration confirmation prompt (`--yes` to skip)
18+
- Bridge/fallback guidance for untranslatable packages
19+
20+
### Changed
21+
- Updated CLI help text for analyze and status commands
22+
- Improved launch rule conversion for `<machine>` and `<test>` tags
23+
- Updated PromptBuilder to support custom rule merging
24+
25+
## [0.1.0] - 2026-02-24
26+
27+
### Added
28+
- Initial release with complete ROS1 to ROS2 migration pipeline
29+
- Five pipeline stages: Ingest, Analyze, Transform, Validate, Report
30+
- BYOM engine support: Claude (CLI/API), Gemini (CLI/API), OpenAI (CLI/API)
31+
- Static knowledge base: API mappings, CMake rules, package.xml rules, launch rules, msg/srv rules
32+
- Full parser suite: Python source, launch XML, msg/srv, CMake, package.xml
33+
- CLI commands: migrate, analyze, config, status
34+
- Jinja2 migration report with git diff
35+
- Telemetry with opt-in local logging
36+
- 692 tests (unit, integration, e2e)

‎CONTRIBUTING.md‎

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
# Contributing to ROSForge
2+
3+
Thank you for your interest in contributing!
4+
5+
## Development Setup
6+
7+
1. Clone the repository:
8+
```bash
9+
git clone https://github.com/Rlin1027/ROSForge.git
10+
cd ROSForge
11+
```
12+
13+
2. Create a virtual environment:
14+
```bash
15+
python -m venv .venv
16+
source .venv/bin/activate
17+
```
18+
19+
3. Install in development mode:
20+
```bash
21+
pip install -e ".[dev]"
22+
```
23+
24+
4. Run tests:
25+
```bash
26+
pytest tests/ -q
27+
```
28+
29+
## Code Style
30+
31+
- We use **ruff** for linting and formatting
32+
- We use **mypy** for type checking
33+
- Run before submitting:
34+
```bash
35+
ruff check src/ tests/
36+
ruff format src/ tests/
37+
mypy src/rosforge/ --ignore-missing-imports
38+
```
39+
40+
## Pull Request Process
41+
42+
1. Fork the repository
43+
2. Create a feature branch (`git checkout -b feature/my-feature`)
44+
3. Write tests for new functionality
45+
4. Ensure all tests pass
46+
5. Submit a pull request
47+
48+
## Reporting Issues
49+
50+
- Use GitHub Issues
51+
- Include: Python version, OS, rosforge version, steps to reproduce
52+
53+
## Adding a New Engine Backend
54+
55+
ROSForge uses a BYOM (Bring Your Own Model) architecture. To add a new AI engine:
56+
57+
1. Create a new directory under `src/rosforge/engine/<name>/`
58+
2. Implement `EngineInterface` from `src/rosforge/engine/base.py`
59+
3. Register in `src/rosforge/engine/registry.py`
60+
4. Add tests in `tests/unit/test_engine_<name>.py`
61+
62+
## Adding Knowledge Base Rules
63+
64+
To extend the static knowledge base:
65+
66+
1. Edit files in `src/rosforge/knowledge/`
67+
2. Or create custom rules via `.rosforge/custom_rules.yaml`
68+
69+
## License
70+
71+
By contributing, you agree that your contributions will be licensed under the Apache License 2.0.

‎README.md‎

Lines changed: 201 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,212 @@
11
# ROSForge
22

3-
AI-driven ROS1 to ROS2 migration CLI tool.
3+
**AI-driven ROS1 to ROS2 migration CLI tool.**
44

5-
## Install
5+
[![CI](https://img.shields.io/github/actions/workflow/status/Rlin1027/ROSForge/ci.yml?branch=main&label=CI)](https://github.com/Rlin1027/ROSForge/actions) [![PyPI](https://img.shields.io/pypi/v/rosforge)](https://pypi.org/project/rosforge/) [![License](https://img.shields.io/badge/license-Apache%202.0-blue)](LICENSE)
6+
7+
## Why ROSForge?
8+
9+
ROS1 reached end-of-life in May 2025. Migrating a production codebase to ROS2 by hand is tedious and error-prone: API namespaces changed, CMakeLists.txt rules are different, launch files moved to Python, and hundreds of `ros::` calls need one-by-one replacement. ROSForge automates this work by combining a static knowledge base of known API mappings with an AI backend that handles the cases rules alone cannot cover. The result is a complete, confidence-scored migration in minutes rather than days.
10+
11+
## Features
12+
13+
- **Full pipeline** — analyze, transform, validate, and report in a single command
14+
- **BYOM (Bring Your Own Model)** — Claude, Gemini, and OpenAI backends; CLI or API mode
15+
- **Auto-fix loop** — runs `colcon build`, feeds errors back to the AI, retries up to N times
16+
- **Interactive mode** — per-file diff review; accept or skip each transformed file
17+
- **Batch workspace migration** — migrate an entire catkin workspace in one pass
18+
- **Custom transformation rules** — override or extend mappings with a YAML file
19+
- **Static knowledge base** — built-in C++/Python API mappings, CMake rules, and launch conversion patterns
20+
- **Cost estimation** — token and USD estimates shown before any API calls are made
21+
- **Confidence scoring** — every output file is rated HIGH / MEDIUM / LOW; low-confidence files are flagged for manual review
22+
23+
## Quick Start
624

725
```bash
26+
# Install
827
pip install rosforge
28+
29+
# Set your preferred AI backend (stored in ~/.config/rosforge/config.toml)
30+
rosforge config set engine.name gemini
31+
rosforge config set engine.mode cli
32+
33+
# Migrate a single ROS1 package
34+
rosforge migrate ./my_ros1_package -o ./my_ros1_package_ros2
35+
```
36+
37+
The migrated package and a `migration_report.md` are written to the output directory.
38+
39+
## Commands
40+
41+
| Command | Description |
42+
|---|---|
43+
| `rosforge migrate <path>` | Migrate a single ROS1 package to ROS2 |
44+
| `rosforge migrate-workspace <path>` | Migrate all packages in a catkin workspace |
45+
| `rosforge analyze <path>` | Analyze a package and report migration complexity without transforming |
46+
| `rosforge config set <key> <value>` | Set a configuration value and persist it |
47+
| `rosforge config get <key>` | Get a single configuration value |
48+
| `rosforge config list` | Print all current configuration values as JSON |
49+
| `rosforge config reset` | Reset configuration to defaults |
50+
| `rosforge config path` | Show the path to the configuration file |
51+
| `rosforge status` | Show the status of an in-progress or completed migration |
52+
53+
## AI Engine Configuration
54+
55+
ROSForge supports three AI backends. Each can run in **cli** mode (calls a locally installed CLI tool, no API key required) or **api** mode (calls the provider's REST API directly, requires an API key).
56+
57+
### Claude
58+
59+
```bash
60+
# CLI mode — requires the Anthropic Claude CLI installed and authenticated
61+
rosforge config set engine.name claude
62+
rosforge config set engine.mode cli
63+
64+
# API mode — requires ANTHROPIC_API_KEY
65+
pip install "rosforge[claude]"
66+
rosforge config set engine.name claude
67+
rosforge config set engine.mode api
68+
export ANTHROPIC_API_KEY=sk-ant-...
69+
```
70+
71+
### Gemini
72+
73+
```bash
74+
# CLI mode — requires the Google Gemini CLI installed and authenticated
75+
rosforge config set engine.name gemini
76+
rosforge config set engine.mode cli
77+
78+
# API mode — requires GOOGLE_API_KEY
79+
pip install "rosforge[gemini]"
80+
rosforge config set engine.name gemini
81+
rosforge config set engine.mode api
82+
export GOOGLE_API_KEY=AIza...
83+
```
84+
85+
### OpenAI
86+
87+
```bash
88+
# API mode — requires OPENAI_API_KEY
89+
pip install "rosforge[openai]"
90+
rosforge config set engine.name openai
91+
rosforge config set engine.mode api
92+
export OPENAI_API_KEY=sk-...
993
```
1094

11-
## Usage
95+
Install all backends at once:
96+
97+
```bash
98+
pip install "rosforge[all]"
99+
```
100+
101+
## Advanced Usage
102+
103+
### Interactive review
104+
105+
Review each transformed file before it is written:
12106

13107
```bash
14-
rosforge migrate ./my_ros1_package
108+
rosforge migrate ./my_package --interactive
15109
```
110+
111+
Press `a` to accept, `s` to skip, `q` to quit and accept all remaining files.
112+
113+
### Auto-fix loop
114+
115+
Build the output with `colcon build` after migration, feed any errors back to the AI, and retry:
116+
117+
```bash
118+
rosforge migrate ./my_package --max-fix-attempts 3
119+
```
120+
121+
### Custom rules
122+
123+
Supply additional or overriding transformation mappings:
124+
125+
```bash
126+
rosforge migrate ./my_package --rules custom_rules.yaml
127+
```
128+
129+
### Skip confirmation
130+
131+
Skip the cost-estimate confirmation prompt (useful in CI):
132+
133+
```bash
134+
rosforge migrate ./my_package --yes
135+
```
136+
137+
### Target ROS2 distribution
138+
139+
The default target is `humble`. To target a different distribution:
140+
141+
```bash
142+
rosforge migrate ./my_package --distro jazzy
143+
```
144+
145+
### Workspace migration
146+
147+
```bash
148+
rosforge migrate-workspace ./catkin_ws -o ./ros2_ws --engine gemini --yes
149+
```
150+
151+
### Analyze without migrating
152+
153+
```bash
154+
# Rich table output in the terminal
155+
rosforge analyze ./my_package
156+
157+
# Machine-readable JSON
158+
rosforge analyze ./my_package --json
159+
160+
# Save JSON report to file
161+
rosforge analyze ./my_package -o analysis.json
162+
```
163+
164+
## Custom Rules
165+
166+
Create a YAML file to add or override transformation mappings:
167+
168+
```yaml
169+
# custom_rules.yaml
170+
version: 1
171+
172+
api_mappings:
173+
cpp:
174+
"ros::NodeHandle": "rclcpp::Node"
175+
"ros::Publisher": "rclcpp::Publisher"
176+
python:
177+
"rospy.init_node": "rclpy.init"
178+
"rospy.Publisher": "rclpy.create_publisher"
179+
180+
package_mappings:
181+
"roscpp": "rclcpp"
182+
"rospy": "rclpy"
183+
184+
cmake_mappings:
185+
"find_package(catkin REQUIRED": "find_package(ament_cmake REQUIRED"
186+
```
187+
188+
Pass the file with `--rules custom_rules.yaml`. Custom mappings take precedence over the built-in knowledge base.
189+
190+
## Development
191+
192+
```bash
193+
git clone https://github.com/Rlin1027/ROSForge.git
194+
cd ROSForge
195+
pip install -e ".[dev,all]"
196+
pytest tests/
197+
```
198+
199+
Lint and type-check:
200+
201+
```bash
202+
ruff check src/
203+
mypy src/
204+
```
205+
206+
## Contributing
207+
208+
Contributions are welcome. Please open an issue before submitting a pull request for significant changes. See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
209+
210+
## License
211+
212+
Apache 2.0 — see [LICENSE](LICENSE) for details.

0 commit comments

Comments
 (0)