1317.49 PlanSys2 커뮤니티와 기여 방법

1317.49 PlanSys2 커뮤니티와 기여 방법

1. 개요

PlanSys2(Planning System 2)는 오픈소스 소프트웨어로서, 전 세계의 로봇 공학 연구자 및 개발자들이 참여하는 커뮤니티를 통해 개발·유지보수된다. 오픈소스 생태계에서 프로젝트의 지속적인 발전은 커뮤니티의 활성도에 직접적으로 의존하며, 코드 기여, 문서화, 버그 보고, 리뷰 등 다양한 형태의 참여가 프로젝트의 품질과 성숙도를 결정한다. 본 절에서는 PlanSys2 커뮤니티의 구조, 참여 경로, 그리고 기여 절차를 체계적으로 다룬다.

2. PlanSys2 프로젝트의 거버넌스 구조

2.1 프로젝트 관리 주체

PlanSys2는 ROS2 생태계의 일원으로서, 주요 개발 및 유지보수는 프로젝트의 핵심 관리자(maintainer)들에 의해 이루어진다. 프로젝트의 원 저작자인 Francisco Martín Rico(Universidad Rey Juan Carlos, 스페인)를 중심으로, 소수의 핵심 개발자가 코드 리뷰, 릴리스 관리, 아키텍처 결정 등의 거버넌스 역할을 수행한다.

ROS2 생태계 내에서 PlanSys2의 위치는 Navigation2(Nav2), MoveIt2 등과 유사한 수준의 커뮤니티 관리 프로젝트(community-maintained project)에 해당한다. Open Source Robotics Foundation(OSRF)이 직접 관리하는 ROS2 코어 패키지와는 달리, 커뮤니티 관리 프로젝트는 자체적인 거버넌스 구조를 갖는다.

2.2 의사결정 프로세스

PlanSys2의 주요 설계 결정은 다음의 경로를 통해 이루어진다.

  • GitHub Issues: 기능 요청(feature request), 버그 보고(bug report), 설계 제안(design proposal) 등이 GitHub 이슈를 통해 제안되고 논의된다.
  • Pull Request 리뷰: 코드 변경은 Pull Request(PR)를 통해 제출되며, 핵심 관리자 또는 지정된 리뷰어의 승인을 거쳐 병합된다.
  • ROS Discourse: ROS 커뮤니티의 공식 포럼인 ROS Discourse(discourse.ros.org)에서 PlanSys2 관련 설계 논의, 릴리스 공지, 사용 사례 공유 등이 이루어진다.

3. 커뮤니티 참여 채널

3.1 GitHub 저장소

PlanSys2의 소스 코드는 GitHub에서 공개되어 있으며, 주요 저장소는 다음과 같다.

  • ros2_planning_system: PlanSys2의 핵심 패키지들(plansys2_core, plansys2_domain_expert, plansys2_problem_expert, plansys2_planner, plansys2_executor 등)이 포함된 메타 저장소이다.
  • plansys2_msgs: PlanSys2에서 사용하는 커스텀 ROS2 메시지, 서비스, 액션 정의를 담고 있다.

GitHub 저장소는 이슈 추적, 코드 리뷰, CI/CD 파이프라인, 릴리스 관리 등 소프트웨어 개발의 전 과정을 지원하는 중심 허브로 기능한다.

3.2 ROS Discourse 포럼

ROS Discourse(https://discourse.ros.org)는 ROS/ROS2 생태계의 공식 토론 플랫폼이다. PlanSys2 관련 주제는 주로 다음의 카테고리에서 다루어진다.

  • General: PlanSys2의 사용법, 설정, 일반적인 질문 등
  • Navigation: Nav2와의 통합 관련 주제
  • Next Generation (ROS2): ROS2 생태계의 일부로서의 PlanSys2 논의

Discourse에서는 장문의 기술적 논의, 설계 제안서(design proposal), 릴리스 공지 등이 게시되며, 이메일 알림 기능을 통해 관심 주제를 추적할 수 있다.

3.3 ROS Answers 및 Robotics Stack Exchange

기술적 질의응답은 ROS Answers(answers.ros.org) 또는 Robotics Stack Exchange(robotics.stackexchange.com)를 통해 이루어진다. PlanSys2의 설치, 설정, 사용 중 발생하는 구체적인 기술적 문제에 대한 질문과 답변이 축적되어 있으며, 태그(tag) 기반의 검색 기능을 통해 관련 문제를 빠르게 탐색할 수 있다.

4. 기여 유형과 절차

4.1 버그 보고

PlanSys2의 사용 중에 발견된 버그는 GitHub Issues를 통해 보고한다. 효과적인 버그 보고는 다음의 정보를 포함해야 한다.

  1. 환경 정보: ROS2 배포판 버전, 운영체제 버전, PlanSys2 버전, DDS 구현체 종류
  2. 재현 절차(reproduction steps): 버그를 재현하기 위한 구체적인 단계별 과정
  3. 기대 동작과 실제 동작: 정상적으로 기대되는 동작과 실제로 관찰된 동작의 차이
  4. 오류 로그: 터미널 출력, ROS2 로그 파일, 스택 트레이스(stack trace) 등
  5. 최소 재현 예제(minimal reproducible example): 가능한 경우, 문제를 재현할 수 있는 최소한의 코드 또는 런치 파일

4.2 기능 요청

새로운 기능의 추가를 요청하는 경우에도 GitHub Issues를 사용한다. 기능 요청 시에는 다음의 사항을 명확하게 기술해야 한다.

  • 동기(motivation): 해당 기능이 필요한 사용 사례 또는 문제 상황
  • 제안 내용(proposal): 구현할 기능의 구체적인 명세
  • 대안 검토(alternatives considered): 고려한 대안적 접근 방법과 그 장단점

4.3 코드 기여

PlanSys2에 코드를 기여하는 절차는 일반적인 오픈소스 소프트웨어의 GitHub 기반 기여 모델을 따른다.

4.3.1 Fork and Pull Request 워크플로

  1. 저장소 포크(Fork): PlanSys2 저장소를 자신의 GitHub 계정으로 포크한다.
  2. 브랜치 생성: 기여할 내용에 맞는 이름의 기능 브랜치(feature branch)를 생성한다. 
    git checkout -b feature/my-improvement

3. **코드 수정**: 해당 브랜치에서 코드를 수정한다.
4. **로컬 빌드 및 테스트**: `colcon build`와 `colcon test`를 활용하여 수정된 코드의 정상 작동을 검증한다.
5. **커밋과 푸시**: 의미 있는 커밋 메시지와 함께 변경 사항을 커밋하고 자신의 포크 저장소에 푸시한다.
6. **Pull Request 생성**: 원본 저장소에 PR을 생성하며, 변경 내용, 동기, 테스트 결과 등을 기술한다.
7. **코드 리뷰 대응**: 리뷰어의 피드백에 따라 코드를 수정하고 재커밋한다.
8. **병합**: 리뷰가 승인되면 핵심 관리자가 PR을 병합한다.

#### 4.3.2 코딩 컨벤션


PlanSys2는 ROS2 생태계의 코딩 표준을 준수한다. 주요 컨벤션은 다음과 같다.

- **C++ 코드 스타일**: ROS2의 C++ 코딩 가이드라인을 따르며, `ament_cpplint`, `ament_uncrustify` 등의 린팅(linting) 도구를 통해 스타일 준수 여부를 자동 검증한다.
- **Python 코드 스타일**: PEP 8을 기반으로 하며, `ament_flake8` 도구를 통해 검증한다.
- **CMake 스타일**: `ament_cmake_lint_cmake` 도구를 활용하여 CMakeLists.txt의 스타일을 검증한다.
- **저작권 헤더**: 모든 소스 파일에는 Apache License 2.0에 준하는 저작권 헤더가 포함되어야 한다.

#### 4.3.3 테스트 작성


코드 기여 시 테스트 코드의 작성은 필수적이다. PlanSys2에서 사용하는 테스트 프레임워크와 도구는 다음과 같다.

- **단위 테스트(Unit Test)**: Google Test(gtest) 프레임워크를 사용한다.
- **통합 테스트(Integration Test)**: `launch_testing` 프레임워크를 활용하여 다중 노드 환경에서의 통합 테스트를 수행한다.
- **린트 테스트(Lint Test)**: `ament_lint_auto` 메타 패키지를 통해 코드 스타일, 저작권 헤더, API 문서화 등을 자동 검사한다.

### 4.4 문서화 기여


PlanSys2의 문서화에 기여하는 것은 코드 기여 못지않게 프로젝트에 중요한 가치를 제공한다. 문서화 기여의 유형은 다음과 같다.

- **API 문서**: 소스 코드 내의 Doxygen 형식 주석을 통해 API 문서를 개선한다.
- **사용자 가이드**: 설치 절차, 튜토리얼, 사용 예제 등의 사용자 대면 문서를 작성하거나 갱신한다.
- **아키텍처 문서**: 시스템 구조, 설계 결정의 근거, 내부 메커니즘 등에 관한 기술적 문서를 보강한다.

문서화 기여 역시 GitHub PR을 통해 이루어지며, 코드 기여와 동일한 리뷰 프로세스를 거친다.

## 5. 오픈소스 라이선스


PlanSys2는 Apache License 2.0 하에 배포된다. Apache License 2.0의 주요 특성은 다음과 같다.

- **허용적 라이선스(Permissive License)**: 상업적 사용, 수정, 배포, 특허 사용이 허용된다.
- **저작권 고지 의무**: 파생 저작물에 원 라이선스와 저작권 고지를 포함해야 한다.
- **특허 부여(Patent Grant)**: 기여자는 기여한 코드에 대한 특허 사용 권리를 묵시적으로 부여한다.
- **상표권 미포함**: Apache License 2.0은 상표 사용 권리를 부여하지 않는다.

이러한 라이선스 조건은 PlanSys2를 학술 연구, 산업용 제품, 상업적 서비스 등 다양한 맥락에서 자유롭게 활용할 수 있도록 한다.

## 6. ROS2 생태계 내에서의 협업 관계


### 6.1 Navigation2(Nav2)와의 협업


PlanSys2는 Nav2와 밀접한 협업 관계를 유지한다. 태스크 플래닝의 결과로 도출된 내비게이션 액션은 Nav2의 경로 계획 및 추종 기능을 통해 실행되며, 이러한 통합은 두 프로젝트의 개발자 간 지속적인 인터페이스 조율을 필요로 한다.

### 6.2 ROS2 공통 인프라 활용


PlanSys2는 ROS2 생태계의 공통 개발 인프라를 활용한다.

- **`rosdistro`**: 패키지 배포 및 버전 관리를 위한 메타데이터 저장소
- **`bloom`**: 릴리스 자동화 도구
- **`build.ros2.org`**: 공식 CI 빌드 팜(build farm)
- **`index.ros.org`**: ROS 패키지 인덱스

이러한 인프라의 활용은 PlanSys2가 ROS2 생태계의 표준 배포 파이프라인을 통해 사용자에게 전달될 수 있도록 보장한다.

## 7. 학술 기여와 인용


### 7.1 학술 논문 인용


PlanSys2를 학술 연구에서 사용한 경우, 다음의 논문을 인용하는 것이 관례이다.

- Martín, F., et al., "PlanSys2: A Planning System Framework for ROS2," *2021 IEEE/RSJ International Conference on Intelligent Robots and Systems (IROS)*, 2021.

학술적 인용을 통해 프로젝트의 가시성(visibility)을 높이고, 개발자 및 연구자들의 기여에 대한 학술적 인정(credit)을 부여할 수 있다.

### 7.2 학술 커뮤니티와의 연계


PlanSys2는 로봇 공학 분야의 주요 학술 대회 및 워크숍에서 정기적으로 발표·논의된다. IROS, ICRA(International Conference on Robotics and Automation), ROSCon 등의 행사에서 PlanSys2 관련 튜토리얼 세션, 기술 발표, 데모 세션이 개최되며, 이를 통해 최신 연구 동향과 커뮤니티의 요구 사항이 프로젝트에 반영된다.

## 8. 요약


PlanSys2 커뮤니티는 GitHub 기반의 오픈소스 협업 모델을 통해 운영되며, 버그 보고, 기능 요청, 코드 기여, 문서화, 학술 인용 등 다양한 형태의 참여를 지원한다. Fork-and-Pull-Request 워크플로, ROS2 코딩 컨벤션 준수, 테스트 코드 작성 등의 표준 절차를 따르는 것이 효과적인 기여의 핵심이다. Apache License 2.0 하에서의 자유로운 사용과 ROS2 생태계 공통 인프라의 활용은 PlanSys2의 접근성과 배포 효율성을 보장한다.