Ultralytics 오픈 소스 프로젝트에 기여하기 위한 시작 팁

오픈 소스 소프트웨어의 기반은 협업, 학습, 공유입니다. 오픈 소스 프로젝트는 사람들이 함께 모여 각자의 역량을 뛰어넘는 무언가를 만들어 가는 좋은 방법입니다. Ultralytics는 오픈 소스의 원칙을 소중히 여기며, 오픈 소스 프로젝트에 기여해 주시기를 언제나 권장합니다.

문서 작성, 코드 검토, 이슈 해결 등을 통해 기여하고 싶지만 어디서 시작해야 할지 모르거나 어려움을 겪고 계신다면, 시작할 수 있도록 도와드리겠습니다. 이 글에서는 Ultralytics 오픈 소스 프로젝트에 기여하기 위한 몇 가지 팁을 안내합니다.

Ultralytics 커뮤니티 기여의 중요성#

기여 방법을 살펴보기 전에 기여가 왜 중요한지 알아보겠습니다. Ultralytics 커뮤니티의 기여가 중요하다고 굳게 믿습니다. 오픈 소스 프로젝트에 참여하면 단순히 더 나은 소프트웨어를 만드는 데 도움을 주는 것 이상의 의미가 있습니다. 기여자는 기술이 개방적이고 협력적이며 끊임없이 발전하도록 하는 데 핵심적인 역할을 합니다. 여러분의 기여는 전 세계 사용자와 개발자가 프로젝트를 활발하게 이용하고 쉽게 접근하며 유익하게 활용할 수 있도록 합니다.

Ultralytics 프로젝트에 기여하는 일은 소프트웨어를 만드는 것뿐 아니라 여러분이 성장할 수 있는 좋은 기회이기도 합니다. 경험 많은 개발자와 함께 일하며 코딩, 문제 해결, 팀워크 역량을 키우고 지침과 모범 사례를 배울 수 있습니다. 여러분의 노력은 전 세계 수천 명이 사용하는 도구에 실질적인 영향을 줄 수 있습니다. 커뮤니티에 참여하면 전문가 네트워크를 넓히고 새로운 기회를 얻으며 포트폴리오를 강화해 고용주에게 더욱 돋보일 수 있습니다.

그림 1. 기여해야 하는 이유. 이미지 제작자: 글쓴이.

Ultralytics 오픈 소스 프로젝트에 기여하는 방법#

좋은 시작점은 Ultralytics 공식 기여 가이드를 확인하는 것입니다. 이 가이드에는 기여의 효과를 높이는 모범 사례와 팁이 담겨 있습니다. 먼저 기여 지침을 이해하고 기여자 라이선스 계약(CLA)에 서명한 다음 코드를 살펴보며 프로젝트에 이미 포함된 내용을 익히세요.

개발에 기여하려는 경우든 최신 코드를 살펴보려는 경우든, 다음 단계는 Ultralytics 저장소를 클론하는 것입니다. 클론한 후에는 프로젝트 디렉터리로 이동해 아래 코드 예시와 같이 패키지를 편집 가능 모드로 설치할 수 있습니다.

git clone https://github.com/ultralytics/ultralytics.git
cd ultralytics
pip install -e .

도움이 필요하면 빠른 시작 가이드에서 원활하게 시작하는 데 필요한 모든 정보를 확인할 수 있습니다.

기여할 수 있는 다양한 영역#

환경 설정을 마치고 프로젝트에 익숙해지면 의미 있는 기여를 할 수 있는 다양한 영역을 살펴볼 수 있습니다. Ultralytics에는 참여할 수 있는 여러 방법이 있으며, 자신의 기술과 관심사에 따라 기여 방식을 선택할 수 있습니다.

다음은 선택할 수 있는 몇 가지 방법입니다.

• 문서: 문서에 기여하면 글쓰기 역량을 키우면서 프로젝트를 자세히 알아볼 수 있습니다. 기존 문서를 개선하거나 누락된 세부 정보를 추가하거나 다른 사람들이 더 쉽게 기여하도록 돕는 새 가이드를 작성할 수 있습니다.
• 버그 수정: 코딩 경험이 있다면 버그 수정을 고려해 보세요. 사소한 조정부터 더 복잡한 문제까지 다양하며, 프로젝트에 실질적인 영향을 미칠 기회를 제공합니다.
• 기능 개선: 더 깊이 있는 작업을 진행할 준비가 되었다면 기능 개선은 도전적이면서도 보람 있는 일이 될 수 있습니다. 여기에는 새 기능 추가, 기존 기능 개선, 프로젝트 로드맵 작업 등이 포함될 수 있습니다.
• 풀 리퀘스트 검토: 풀 리퀘스트 검토는 기여할 수 있는 또 다른 유용한 방법입니다. 특히 프로젝트의 표준과 모범 사례에 익숙하다면 더욱 그렇습니다. 피드백을 제공하고 개선 사항을 제안하면 코드베이스의 품질과 무결성을 유지하는 데 도움이 됩니다.
• 커뮤니티 토론: 협업과 아이디어 공유를 즐긴다면 커뮤니티 토론에 참여하는 것도 훌륭한 기여 방법입니다. 진행 중인 대화에 참여하고, 새로운 아이디어를 제안하거나, 통찰과 해결책을 제공해 다른 사람을 도와주세요.

각 영역은 고유한 기여 방법을 제공하므로 자신의 강점과 관심사에 가장 잘 맞는 영역을 선택할 수 있습니다. 아무리 작은 기여라도 Ultralytics의 성장과 발전에 중요한 역할을 한다는 점을 기억하세요.

그림 2. 성장하는 커뮤니티에서는 모든 기여를 소중히 여깁니다. 이미지 출처: Envato Elements.

Ultralytics 오픈 소스 문서에 기여하기#

Ultralytics 문서에 기여할 때는 기존 문서를 검토하고 개선이 필요한 영역을 보여 주는 문제나 토론이 있는지 확인하세요. 이렇게 하면 가장 필요한 부분에 기여를 집중할 수 있습니다.

문서를 작성하거나 편집할 때는 일관성을 유지하기 위해 프로젝트 지침을 따르는 것이 중요합니다. 다음은 몇 가지 서식 지정 팁입니다.

• 항상 Markdown 서식을 사용하세요.
• 각 문서는 명확한 소개로 시작하고, 간결하고 이해하기 쉬운 표현을 사용하세요.
• 목록에는 글머리 기호를 사용하고, 링크에는 설명이 포함된 텍스트를 사용하며, 페이지가 빠르게 로드되도록 이미지 크기를 1 MB 미만으로 유지하세요.
• 서식에 관한 질문이 있다면 이전 문서의 서식이 어떻게 지정되었는지 확인하는 것이 쉽게 검토하는 방법입니다.

그림 3. Markdown 서식 예시(왼쪽)와 최종 시각화된 문서(오른쪽)입니다. 이미지 제공: 작성자.

초안을 작성한 후에는 문서를 로컬에서 빌드하여 미리 보는 것이 중요합니다. 제출하기 전에 문제를 발견할 수 있습니다. 먼저 저장소를 복제하고 프로젝트 디렉터리로 이동하세요.

git clone https://github.com/ultralytics/ultralytics.git
cd ultralytics

다음으로 필요한 종속성을 설치할 수 있습니다.

pip install -e ".[dev]"

마지막으로 문서를 빌드하고 로컬에서 실행해 변경 사항을 검토하세요:

python docs/build_docs.py
python -m http.server --directory site

웹 브라우저에서 http://127.0.0.1:8000/으로 이동하면 로컬에서 빌드한 문서를 볼 수 있습니다.

명확성, 정확성, 일관성을 검토한 후 작성한 문서에 대한 명확한 설명을 포함해 풀 리퀘스트를 제출할 수 있습니다. 문서의 주제와 가장 잘 맞는 적절한 섹션(가이드, 솔루션, 통합 등)에 문서를 배치하세요. 관련 섹션을 확인할 수 있도록 index.md 파일과 전체 mkdocs.yml 파일도 살펴보고 필요한 부분을 업데이트하세요. 세부 사항에 주의를 기울이면 검토 과정이 원활하게 진행되고 기여 내용이 프로젝트에 잘 통합됩니다.

오픈 소스 코드에 기여할 때 유의할 사항#

Ultralytics 프로젝트에 코드를 기여할 때는 코드가 깔끔하고 유지 관리하기 쉬우며 통합하기 편하도록 지원하는 모범 사례를 따르는 것이 중요합니다. 다음은 유념해야 할 몇 가지 핵심 사항입니다:

• 코드 중복 방지: 가능한 한 기존 코드를 재사용하고 불필요한 인수를 최소화하세요.
• 작고 집중적인 변경 적용: 대규모 수정 대신 작고 구체적인 변경에 집중하세요.
• 코드 간소화 또는 제거: 코드를 간소화하거나 불필요한 부분을 제거할 기회를 찾아보세요.
• 효과적인 독스트링 작성: 코드의 기능을 명확히 설명하고 관련 리소스에 연결하세요.
• 불필요한 종속성 방지: 꼭 필요한 경우에만 종속성을 추가하세요.

그림 4. 소스 코드 문서화 모범 사례.

코드베이스의 장기적인 유지 관리 가능성도 반드시 고려해야 합니다. 변경하기 전에 수정 사항이 Ultralytics를 사용하는 다른 사람의 기존 코드를 손상시킬 수 있는지 자문해 보세요. 그렇다면 이를 해결할 방법을 고려하고 변경 사항이 최대한 호환되도록 하세요.

기여할 코드를 작성한 후에는 테스트해야 합니다. 변경 사항을 제출하기 전에 pytest와 같은 프레임워크를 사용해 테스트할 수 있습니다. 일관된 코드 포맷도 기여 과정에서 매우 중요합니다. Ruff와 같은 도구는 스타일의 일관성을 유지하고 코드의 일반적인 오류나 불일치를 찾아내는 데 도움이 됩니다.

풀 리퀘스트 검토#

풀 리퀘스트(PR)를 검토하는 것은 훌륭한 기여 방법입니다! 누군가 변경 사항을 메인 프로젝트에 병합해 달라고 요청하면 PR이 생성됩니다. PR은 Ultralytics 프로젝트가 원활하게 운영되도록 돕습니다. PR을 검토할 때는 변경 사항이 적용된 이유를 이해해야 합니다. 작성자는 업데이트의 목적과 이점을 명확히 설명해야 하며, PR에는 충분한 테스트를 수행했다는 근거가 있어야 합니다.

그림 5. 풀 리퀘스트란 무엇인가요?

중점적으로 살펴볼 몇 가지 핵심 사항을 알아보겠습니다.

• 단위 테스트 확인: PR에 새 기능이나 변경 사항에 대한 테스트가 포함되어 있는지 확인하여 코드가 예상대로 작동하고 문제를 일으키지 않는지 검증하세요.
• 문서 업데이트 검토: 예시, API 참조, 기타 관련 세부 정보를 포함해 변경 사항이나 새 기능을 반영하도록 문서가 업데이트되었는지 확인하세요.
• 성능 영향 평가: 변경 사항이 성능에 미치는 영향을 고려하세요. 필요한 경우 성능 벤치마크나 추가 테스트를 요청하세요.
• CI 테스트 확인: 코드 서식 검사와 단위 테스트 결과를 포함해 모든 지속적 통합(CI) 테스트가 통과했는지 확인하세요.
• 수정 사항 협업: 테스트가 실패하면 PR을 승인하기 전에 작성자와 협력해 문제를 해결하세요.

리뷰어는 문제나 우려 사항에 대해 구체적이고 명확한 피드백을 제공해야 합니다. 개선 방안을 제안하고 작성자가 잠재적인 문제를 충분히 검토하도록 질문하세요. 코딩, 테스트, 문서 작성에서 모범 사례를 따르도록 권장하고 도움이 될 만한 자료도 주저하지 말고 안내하세요. 마지막으로 작성자가 PR에 들인 노력을 항상 인정해 주세요. 긍정적인 피드백은 오픈 소스 커뮤니티의 친근하고 협력적인 분위기를 유지하는 데 도움이 됩니다.

기여는 모두 커뮤니티를 위한 것입니다#

Ultralytics와 같은 오픈 소스 프로젝트에 기여하면 공동체에 참여한다는 고무적인 경험을 할 수 있습니다. 코드를 작성하거나, PR을 검토하거나, 문서를 업데이트하거나, 토론에 참여하는 등 모든 노력이 프로젝트의 성장과 발전에 도움이 됩니다. GitHub, Discord, Reddit 또는 다른 포럼에서 이슈에 답변하거나 대화에 참여하는 것은 기여와 교류를 위한 소중한 방법입니다. 아무리 작은 기여라도 큰 영향을 미치며, 참여하는 모두를 위한 협력적이고 서로 돕는 환경을 조성하는 데 도움이 됩니다.

Ultralytics는 오픈 소스 커뮤니티의 혁신을 이끄는 데 열정을 쏟고 있습니다. GitHub 저장소를 방문해 최신 소식을 확인하세요. 활기찬 커뮤니티에 참여하고 농업과 제조업 등 다양한 산업에 미치는 영향을 살펴보세요.