How to Contribute - space-station-os/space_station_os GitHub Wiki

Last updated: 2025-08-14

This document outlines how to contribute to the Space Station OS (SSOS) project.

1. Development Workflow

1.1 Branching and Pull Request Process

A. Create Feature Branches

  • Branch from the current development base (e.g., v0.8.4-dev).
  • Each branch must correspond to a single issue (e.g., feature, bug, or refactor).

B. Submit a Pull Request

  • Open a PR into the current *-dev branch.
  • One PR per issue.
  • PR title must reference the issue (e.g., Fix thermal bug (#123)).

C. Review and Merge

  • PRs are reviewed and merged one by one.
  • If a new issue depends on code from an earlier branch, base it on that branch.

D. Release

  • At the end of each development cycle (typically every 2–3 months), the maintainer:
    • Merges the current *-dev branch into main
    • Creates a new release tag (e.g., v0.8.4)

Branch and PR Policy

1.2 Branch Types

Branch Purpose
main Stable release entry point
*-dev Active development base (e.g., v0.8.4-dev)
hotfix/* Emergency fixes to main
feature/*, bugfix/* Feature or issue-specific branches

1.3 Naming Conventions

  • Branches:
    • feature/feature-name
    • bugfix/short-description
    • hotfix/issue-name
  • Tags:
    • vMAJOR.MINOR.PATCH (e.g., v0.8.4, v0.8.3.1)

Do not commit directly to main or *-dev. Use clean, atomic commits with meaningful messages.
Use squash merge unless multiple commits provide meaningful history.

2. Project Backlog and Issue Guidelines

We follow an agile development process with 2–3 month iterations. The system evolves incrementally through continuous contributions, guided by a project backlog and structured issue tracking.

2.1 Project Backlog

The GitHub Project board titled SSOS root backlog is our central task management tool:
https://github.com/orgs/space-station-os/projects/2

backlogimage

2.1.1 Columns and Their Purpose

A. Job-post TODO

  • Open ideas or "wishlist" items
  • Anyone can post issues here

B. Assigned TODO

  • Selected tasks for upcoming work
  • Prioritized by the backlog master

C. In Progress

  • Work currently being developed
  • Anyone may move assigned issues here

D. Request for 'Done'

  • Marked complete by the developer
  • Backlog master reviews before acceptance

E. Done

  • Finalized, reviewed, and closed
  • Do not modify without permission

2.2 Issue Writing Guidelines

All new features should start with a use case and acceptance criteria (Bug reports may be exempt from full story structure).

The issues should include:

  • User Story: Explain the context, background, and user need.
  • Acceptance Criteria: Define the specific conditions that mark the issue as complete.

See https://github.com/space-station-os/space_station_os/wiki/Coding-Rules for details.

3. Contribution Standards

Space Station OS is currently being developed using ROS 2 as its integration framework. This choice accelerates development toward a future flight-ready version. Therefore, the guidelines below assume ROS 2 as the default software environment.

3.1 Coding Standards

  • Python: Follow PEP8
  • C++: Follow Google C++ Style Guide
  • Use modular, reusable functions
  • Avoid hardcoded values; prefer config files
  • Comment complex logic
  • Provide docstrings or header comments for all functions

3.2 Coding Rules

See https://github.com/space-station-os/space_station_os/wiki/Coding-Rules for details.

3.3 Version Control Practices

  • Use branches for all development
  • Base all changes on a tracked GitHub issue
  • Refer to the central backlog for tracking and coordination

3.4 Using the [WIP] Tag for Incomplete Pull Requests

  • If your pull request is not yet ready for review or merging, please indicate this by adding the [WIP] tag at the beginning of the pull request title. This helps reviewers avoid starting a review before the work is complete, and makes it clear that the PR is still in progress.

Once the changes are ready for review, remove the [WIP] tag and update the description accordingly.

4. Testing Standards

SSOS is currently in a proof-of-concept phase. Automated testing and CI are under gradual adoption, but we prioritize keeping the development flow lightweight and accessible. At this stage, contributors are not blocked by failing tests.

4.1 Unit Testing

  • Frameworks like pytest or Google Test may be used, but are optional.
  • Manual testing or log-based verification is acceptable during v0.8.x.
  • Code should be structured in a modular and testable way.
  • C++ logic may use gtest for isolated functions.
  • ROS 2 users may prefer launch_test, pytest with rclpy, or NodeTester.

4.2 Integration and System Testing

  • ROS nodes and hardware code should be validated using:
    • Simulation
    • launch_test
    • Manual procedures
  • Contributors are encouraged to cover representative use-case behavior, but no strict enforcement exists during v0.8.x.

4.3 CI Integration

  • GitHub Actions runs colcon build (required) and colcon test (non-blocking).

Policy for v0.8.x:

  • Build must succeed in CI.
  • Tests are executed automatically but are non-blocking; failures will not prevent merging.
  • Maintainers may fix broken tests opportunistically when noticed.

Policy for v0.9.x and beyond:

  • We will revisit stricter enforcement of tests once the project matures.
  • Core packages may then require smoke tests or full test suites.

4.4 Contributor Guidelines

  • When submitting a PR, please describe briefly how you validated your code (manual test, simulation run, or automated test if available).
  • Contributors are welcome to add tests, but it is not mandatory in v0.8.x.
  • Keep in mind that future versions (v0.9.x and beyond) may enforce stricter requirements.

5. Technical Meetings

We hold a bi-weekly SSOS Technical Meeting to discuss current development and roadmap planning.

5.1 Schedule

-　12am (midnight) – 0:45am JST every other Tuesday / 3pm – 3:45pm UTC every other Monday

5.2 Participation

  • Google Meet link: Video call link: https://meet.google.com/mqi-hmzx-jir (Joining does not require approval)
  • Open to all contributors regardless of experience
  • Please contact us to confirm the next meeting date

6. Contact

If you have questions or ideas, please contact the maintainers or raise an issue with the meta label.
You may also reach out to:
Hiroki Kato on LinkedIn

This contribution guide is under active development. Please feel free to suggest changes via Pull Request or GitHub Issue.