[76일차]오픈소스 프로젝트 구축 및 자동화

오픈소스 프로젝트는 거창한 아이디어에서 시작되는 것이 아니라, 개발 과정에서 겪는 불편함을 해결하려는 작은 노력에서 시작된다. 본 가이드는 효율적인 오픈소스 운영을 위한 레포지토리 설정부터 GitHub Actions를 활용한 자동화 검사까지의 과정을 다룬다.

1. 프로젝트 주제 선정 및 방향성

오픈소스의 주제는 복잡한 로직보다는 다른 개발자들이 쉽고 유용하게 사용할 수 있는 기능에 집중하는 것이 좋다.

• 실용성: lodash.js나 immer.js처럼 복잡한 내부 구동 과정을 몰라도 결과를 즉시 확인할 수 있는 도구가 좋은 예시이다.
• 확장성: 사용자들의 다양한 요구사항을 반영할 수 있도록 구조적 유연성을 확보해야 한다.
• 필요성: 개발 과정 중 반복적으로 발생하는 불편함을 해결하는 유틸리티 성격의 라이브러리는 훌륭한 주제가 된다.

2. 레포지토리 생성 및 환경 설정

2.1 Organization 기능 활용

개인 계정보다 GitHub의 Organization 기능을 이용하여 레포지토리를 생성하는 것이 권장된다. 이를 통해 연관된 프로젝트들을 논리적으로 그룹화하여 관리할 수 있으며, 팀 단위의 권한 부여 및 협업이 훨씬 용이해진다.

2.2 브랜치 보호 규칙(Branch Protection Rule) 설정

오픈소스 프로젝트는 불특정 다수가 참여하므로 무분별한 Merge로 인한 코드 베이스 오염을 방지해야 한다.

• 코드 리뷰 필수화: 특정 인원 이상의 승인이 있어야만 Merge가 가능하도록 설정한다.
• 상태 체크 통과 필수: CI(Continuous Integration) 테스트가 성공해야만 병합될 수 있도록 강제한다.

3. 협업을 위한 문서화 표준화

3.1 이슈 및 풀 리퀘스트 템플릿

협업의 일관성을 위해 GitHub의 Issue 및 Pull Request(PR) 템플릿을 추가한다. 이는 기여자가 정보를 누락하지 않도록 가이드 역할을 수행하며, 관리자의 검토 시간을 단축시킨다.

3.2 상세한 README 작성

README는 프로젝트의 얼굴이다. 단순한 제목 나열이 아닌, 다음의 항목들을 반드시 포함하여 작성한다.

• 프로젝트 소개: 핵심 가치와 목적 명시
• 주요 특징: 다른 라이브러리와의 차별점
• 설치 및 사용법: 빠른 시작을 위한 코드 예제
• 기여 방법(Contributing Guide): 프로젝트 참여 규칙 안내

4. GitHub Actions를 통한 PR 검증 자동화

프로젝트의 품질 유지를 위해 PR이 생성될 때마다 본문 작성 여부를 자동으로 확인하는 워크플로우를 설정한다.

4.1 워크플로우 설정 (.github/workflows/pr-check.yml)

아래의 YAML 코드는 PR 생성 시 본문(Body)이 비어있을 경우, 자동으로 안내 코멘트를 남기고 PR을 닫도록 설계된 자동화 스크립트이다.

name: Pull Request Check

on: 
  pull_request: 
    types: [opened, synchronize]

jobs:
  check: 
    runs-on: ubuntu-latest
    permissions: 
      pull-requests: write
    steps: 
      - name: PR 본문 존재 여부 확인
        uses: actions/github-script@v7
        with:
          script: |
            async function run() {
              const pull_request = context.payload.pull_request;

              if (!pull_request) {
                console.log("Pull Request 데이터를 찾을 수 없습니다.");
                return;
              }

              const body = pull_request.body;

              // PR 본문이 비어있거나 내용이 없는 경우
              if (!body || body.trim().length === 0) {
                // 1. PR에 안내 코멘트 추가
                await github.rest.issues.createComment({
                  owner: context.repo.owner,
                  repo: context.repo.repo,
                  issue_number: pull_request.number,
                  body: "⚠️ 해당 PR은 가이드라인(본문 작성)을 준수하지 않았기 때문에 자동으로 닫힙니다. 내용을 보강하여 다시 PR을 생성해 주세요.",
                });

                // 2. PR 상태를 Closed로 변경
                await github.rest.pulls.update({
                  owner: context.repo.owner,
                  repo: context.repo.repo,
                  pull_number: pull_request.number,
                  state: "closed",
                });
              }
            }

            run();

4.2 자동화 스크립트의 기대 효과

• 운영 효율 증대: 기본 규칙을 지키지 않은 PR을 관리자가 일일이 확인하고 거절하는 수고를 덜어준다.
• 기여 가이드 강화: 기여자에게 프로젝트 참여 시 문서화의 중요성을 즉각적으로 인지시킨다.
• 코드 품질 유지: 자동화된 검사를 통해 최소한의 형식을 갖춘 코드만이 검토 단계에 진입하도록 보장한다.