Skip to main content

​
Getting Started

Before contributing, ensure you have completed the installation and workspace setup as described in the Installation guide.

​
Development Workflow

1

Create a feature branch

Create a new branch from main for your changes:
git checkout -b feature/your-feature
Use descriptive branch names that indicate the purpose of your changes.
2

Make changes and test

Develop your feature or fix, ensuring you test thoroughly in simulation.
With symlink install, you can edit .sdf and .launch.py files without rebuilding. For other changes, see When to Rebuild.
3

Commit your changes

Follow the commit message conventions (see below):
git commit -m "Add: obstacle avoidance algorithm"
4

Push to GitHub

Push your branch to the remote repository:
git push origin feature/your-feature
5

Create a pull request

Open a pull request on GitHub with a clear description of your changes.

​
Commit Message Conventions

All commit messages must use one of these prefixes:
PrefixUse CaseExample
Add:New features or capabilitiesAdd: obstacle avoidance algorithm
Fix:Bug fixesFix: robot spawning position
Update:Changes to existing codeUpdate: camera parameters
Remove:Deletions of code or featuresRemove: deprecated sensor node
Docs:Documentation changesDocs: update installation guide
Refactor:Code restructuring without behavior changesRefactor: simplify navigation logic
Commit messages should be concise but descriptive. Focus on what changed and why it matters.

​
Pre-Push Checklist

Before pushing your changes, ensure:
  • Code builds without errors (colcon build --symlink-install)
  • Test world launches successfully (ros2 launch lunabot_simulation moon_yard.launch.py)
  • Changes tested thoroughly in simulation
  • Documentation updated (if applicable)
  • Debug statements and temporary code removed
  • Interface contracts updated (if you renamed topics/actions/frames)
CI runs interface contract checks on every pull request. If you rename or remove ROS interfaces, update .github/contracts/interface_contracts.json in the same PR.

​
Adding New Code

​
Python Nodes

When adding a new Python node:
  1. Place it in the appropriate package subdirectory (e.g., lunabot_navigation/lunabot_navigation/)
  2. Update setup.py to register the entry point:
entry_points={
    'console_scripts': [
        'your_node = package_name.your_node:main',
    ],
},
  1. Rebuild the workspace:
colcon build --symlink-install --packages-select package_name
source install/setup.bash

​
Launch Files

  1. Add your launch file to the launch/ directory of the appropriate package
  2. Ensure it’s installed in CMakeLists.txt:
install(DIRECTORY
  launch
  DESTINATION share/${PROJECT_NAME}
)
  1. Rebuild the package

​
World Files

  1. Add .sdf world files to lunabot_simulation/worlds/
  2. Ensure the worlds directory is installed in CMakeLists.txt:
install(DIRECTORY
  worlds
  DESTINATION share/${PROJECT_NAME}
)
  1. Rebuild lunabot_simulation

​
CI Interface Contract Checks

The CI pipeline runs check_interface_contracts.py to verify that required ROS interfaces haven’t been accidentally renamed or removed.
Interface contracts are guarantees about the topics, actions, and TF links that must exist in the codebase. They prevent breaking changes to critical robot communication interfaces.The contract file (.github/contracts/interface_contracts.json) defines:
  • Topics: Required publishers and subscriptions with their message types
  • Actions: Required action servers and clients
  • TF Links: Required coordinate frame transformations
  • Deferred Topics: Future interfaces not yet enforced

​
When to Update Contracts

Update .github/contracts/interface_contracts.json in the same PR when you:
  • Rename a topic, action, or frame link
  • Change the message/action type of a contracted interface
  • Move interface declarations to a different source file
Mission-state topics listed in deferred_topics are not enforced until the state manager lands in main.

​
Example Contract Entry

{
  "name": "/hazards/front",
  "type": "sensor_msgs/msg/PointCloud2",
  "kind": "publisher",
  "source": "src/lunabot_perception/lunabot_perception/hazard_detection.py"
}

​
Getting Help

If you have questions or need assistance:

Build docs developers (and LLMs) love

Get started for freeTalk to us