오픈소스 만들어 Github에 올릴 때 하면 좋은 체크리스트 .. (1)

아직은 진행중이라 Private으로 진행하고 있지만 간단한 오픈소스를 만들어 공개해보려고 한다.

 

외부 OpenAPI를 호출하는 아주 단순하고 목적이 명확한 클라이언트다.

기능이야 문서 보고 Copilot과 함께 조금씩 개선하면 되는데

공개하는데 비슷한 생각을 가진 사람과 이런저런 얘기하고 만들어가면

재밌을 것 같아서 오픈소스 관련 내용을 찾아봤다.

 

여러개 찾았는데 그중 내가 필요한 내용들을 정리했다.

---

https://github.blog/enterprise-software/collaboration/a-checklist-and-guide-to-get-your-repository-collaboration-ready/

A checklist and guide to get your repository collaboration-ready

 

오픈소스 만든 메인테이너의 가장 중요한 책임은 다른 사람들이 본인의 프로젝트를

적절하게 사용하고, 이해하고, 기여할 수 있도록 하는 것이다.

이런 미션을 지원하기 위해 Github이 있다. Github 기능들을 소개한다.

 

1. Repository settings

Visibility

Repository -> Settings 탭에서 수정할 수 있다.

Public

누구나 접근할 수 있고 코드를 로컬에 다운로드할 수 있고 이슈를 만들고 P/R을 보낼 수 있다.

불특정 다수로부터 기능이 잘 동작하는지 피드백을 받을 수 있고 다양한 개선 방법도 들을 수 있다.

보안 정보가 없는 개인프로젝트에 적합하고 회사 프로젝트에는 적합하지 않다.

 

Internal

Github Enterprise에서 사용 가능한 Visibility 옵션이다.

조직 내부 누구나 접근 가능하지만 외부에서는 접근할 수 없다.

민감한 정보가 없는 회사 프로젝트에 어울린다.

 

Private

가장 제한적인 옵션이다. 초대한 사람만 접근 가능하다. 

 

Collaborators

특정 개인이나 조직을 프로젝트에 초대하는 옵션이다.

읽기 전용, P/R과 커밋 또는 Admin 같은 역할을 부여할 수 있다.

Private과 차이점은 초대 이후 역할을 부여할 수 있다는 점이다.

 

Protect the main branch

Repository rule을 이용하여 main branch에 바로 commit 하는 것을 막을 수 있다. (다양한 기능 존재)

최소 한 명 이상의 승인을 받아야 한다면 `CODEOWNERS` 파일을 이용한다.

추가로 P/R 마다 unit test 같은 자동화된 실행이 필요하다면 status checks를 이용한다.

 

 

2. Repository contents

소프트웨어 프로젝트는 코드 작성만 포함된 게 아니다.

이 프로젝트가 왜 만들어졌는지, 잘 사용하는 방법, 기여하는 방법 등
협력자와의 가이드 역할도 해야 한다.

 

README.md

해당 repository를 방문한 사람이 가장 처음 보는 파일이다.

프로젝트의 기능과 어떻게 설정하고 사용하는지 적혀있어야 한다.

 

LICENSE.md

해당 repository에 있는 코드와 콘텐츠에 대해 다른 사람들이 할 수 있는 것과 할 수 없는 것이 정의되어 있다.

프로젝트에 가장 적합한 라이선스에 대한 지침은 choosealicense.com에서 확인하고 repository에 라이선스를 추가하자.

 

CONTRIBUTING.md

해당 파일에 프로젝트에 새로운 코드, 문서 등 기여하는 방법과 이유를 명확하게 적어서

잠재적 기여자가 직면할 혼란과 마찰을 줄인다.

짧은 경우 README에 적어도 상관없지만 두 문단 이상인 경우 파일 분리하는 걸 추천한다.

 

분리된 파일에는 메인테이너가 원하는 기여 유형, 새로운 기능과 버그 수정 제안 방법,

P/R 제출 과정, 그리고 코딩 표준과 스타일 가이드라인에 대한 정보가 포함되어야 한다.

GitHub docs 프로젝트를 참고 (지금은 지워졌다. 필요 없을지도??)

 

CODEOWNERS

전체 또는 파일 확장자나 폴더 별로 1명 이상의 코드 책임자를 지정할  수 있다.

P/R이 생성되면 수정된 코드에 대해 자동으로 리뷰어 할당이 된다.

"·. md" 확장자가 있으면 안 된다.

 

CODE_OF_CONDUCT.md

프로젝트 참여자가 따라야 할 사회적 규범과 규칙, 책임을 설정한다.

 

이러한 파일은 사람들이 저장소에 훨씬 더 쉽게 접근할 수 있고, 이해가 쉬워지며,

기여하는 게 더 자연스럽게 흐르는 걸 볼 수 있다.

 

 

3. Automation and checks

Never send a human to do a machine's job

 

 

Linting

Linters는 다양한 에러를 감지하고 일관된 코드 스타일을 유지하기 위해 코드를 분석하는 도구다.

Super-Linter

 

Building and testing

프로젝트에서 사용하는 언어와 프레임워크에 따라 다르겠지만 대부분의 repository에서 자동으로 실행 가능하다.

Github Workflow 마켓플레이스에서 build, Test App & Actions 검색해서

본인 repository에 맞는 도구를 찾자.

 

Checks

앞에서 말한 자동화된 도구(Linter, 빌드, 테스트)를 추가하면 실패하는 경우 배포하는 걸 막을 수도 있다.

status checks를 구성해서 앱이 제대로 테스트하는지 확인하는데 도움 된다.

 

이런 자동화 도구와 status checks를 통해 repository 기여의 품질과 일관성의 신뢰를 높이고

자동 실행되기 때문에 관리하는데 더 적은 시간을 사용한다.

 

 

4. Security

 

Roles

협력자에게 역할과 권한 주는 걸 결정할 때는 신중해야 한다.

Writer는 신뢰하는 개인을 위한 것이다.

Admin은 제품 방향을 관리하고 검토하는 핵심 인물을 위한 것이다.

 

Secrets management

API keys나 비밀번호, 인증서 같이 비공개로 유지해야 할 예민한 데이터를 Secrets라고 한다.

코드라 로그에 직접 입력하면 안 되고,

third pary keystore나 GitHub의 secret-management 도구를 사용하면 된다.

 

Security scanners

대부분의 애플리케이션 코드 80~90%는 third pary 소스(프레임워크, 패키지)가 차지한다.

Dependabot은 공개 repository에서 사용할 수 있고, 모든 조직에서 자동으로 활성할 할 수 있다.

불안정한 third pary소스가 발견되면 알림을 주고 수정 방법을 제공한다.

Dependabot이 활성 중인지 확인하려면 repository의 보안탭을 확인한다.

 

 

5. Advanced options

Issue templates

버그 수정이나 개선사항에 대한 문의할 때 issue 기능을 사용하는데

기본적으로 구조화되지 않아 필요한 모든 정보를 알기 위해선 여러 번의 핑퐁이 필요하다.

하지만 issue templates를 만들어 가이드를 주면 필수와 옵션 정보를 입력받을 수 있어

이슈 생성부터 대부분의 정보를 알 수 있다.

 

 

6. Next steps

Responsiveness

메인테이너로서 당신의 응대는 해당 프로젝트가 건강하고 협력하는 환경을 만드는데 중요한 역할을 한다.

이슈와 P/R에 신속하게 대응하고 피드백을 주며, 새 기여자에게 가이드 주는 것까지 포함한다.

변경사항에 대응하고 문제 해결하는 전념할 별도 시간을 따로 설정하고 측정도 하면 좋다.

 

 

Project management

업무를 관리하고 진행상황을 시각화하기 위해 GitHub Project를 설정하면 좋다.

다른 사람들이 프로젝트의 상태를 이해하고 기여할 수 있는 부분을 확인하는데 좋다.

 

Visibility

앞에 소개한 방법들을 적용해서 잘 관리는 됐지만 아무도 알지 못하면 쓸모가 없다.

블로그 포스트나 데모, 프로젝트 랜딩 페이지 등을 통해 프로젝트를 홍보하자.

많은 사람들이 프로젝트 존재에 대해 알수록 더 많은 잠재적 기여자와 사용자를 유치할 수 있다.

 

Community engagement

커뮤니티와 소통하는 것은 건강하고 협력하는 환경을 만드는데 중요하다.

체크리스트를 출력하여 GitHub repository를 생성하거나 수정하

Issue Template 활용해서 개선하자!!