Skip to content

Conventions

Jump to bottom Edit New page
hyoseong edited this page Dec 30, 2025 · 74 revisions

코드 리뷰를 하면서 팀원 간에 합의한 개발 관습을 문서화합니다. 항상 최신의 상태를 유지하기 위해서 팀원 모두 노력해주셨으면 좋겠습니다.

이슈 관리

  • 무료 프로젝트 관리 기능인 깃허브 프로젝트를 통해서 이슈(Jira의 티켓 개념)를 관리합니다.
  • 이슈를 생성할 때는 이슈 유형(Type)을 반드시 선택해주시고, 프로젝트에 추가 후 우선 순위(Priority)와 예상 소요 시간(Est)를 함께 넣어주세요.
  • 이슈를 생성할 때는 스프린트(Sprint)와 상태(Status)는 비워두어 일단 백로그(Backlog)에 두도록 합니다.
  • 이슈는 팀 회의 때 Grooming, Triage, Planning 과정을 거친 후에 스프린트에 추가하는 것이 원칙입니다.
  • 긴급 이슈가 있거나 스프린트에 To Do 이슈가 소진되었을 때는 디스코드에서 소통 후에 현재 스프린트에 추가해주세요.
  • 자율적인 협업과 자발적인 기여를 위해서 특별한 사유가 없다면 이슈를 생성할 때 담당자를 설정하지 않습니다.
  • 이슈의 상태는 스프린트에 추가되었을 때 부터 To Do로 설정해주세요.
  • 작업을 시작하시면 이슈의 상태를 반드시 In Progress로 옮겨주세요. (많이 까먹는 부분입니다.)
  • 이슈가 연결된 Pull Request가 병합되면 이슈는 자동으로 Done 상태로 전환됩니다.
  • 동시에 2개 이상의 이슈를 할당하지 않도록 주의해주세요. WIP가 2보다 커지면 팀의 리뷰 부담이 커지게 됩니다.
  • PM이 구해질 때 까지 모두가 PM이라는 마음가짐으로 프로젝트에 임해주세요. 스스로 티켓을 생성하고 요구 사항을 상세히 작성해주세요.
  • 서브 이슈는 Spike 티켓에서 파생된 Action 티켓에 한해 사용합니다.
  • 서브 이슈가 완료되지 않아도, 상위 Spike 티켓(Parent Issue)은 완료 처리될 수 있습니다.

PR 관리

  1. 프로젝트 보드에서 To Do 상태의 티켓을 선택하고 본인에게 할당합니다.
  2. 프로젝트 설정
  1. 브랜치 생성
  • main 브랜치에서 새로운 feature 브랜치를 생성합니다.
  • 브랜치 이름에는 -, _ 외의 특수문자 사용은 제한됩니다.
    참고 이슈
  1. 기능 구현 및 커밋
  • 브랜치 내에서 소스 코드를 수정하고 커밋합니다.
  • 변경이 모두 완료되면 포크받은 리포지토리의 브랜치를 푸시합니다.
  1. 테스트 작성
  • 기여한 코드가 정상적으로 동작하는지 확인할 수 있는 테스트 코드를 작성합니다.
  1. PR 생성
  • Pull Requests 페이지에서 새로운 PR을 생성합니다.
  • PR의 제목과 설명은 가급적 한국어로 작성해주세요. 이슈 제목과 일치해주면 나중에 찾기가 편합니다.
  • PR이 등록된 이슈와 연관되어 있다면, PR 생성 후 오른쪽 사이드바의 Development 항목에서 해당 이슈를 선택해 연결해주세요.
PR 이슈 연결 예시
  1. PR 리뷰 및 병합
  • 최소 한 명 이상의 관리자가 PR을 검토하고 코멘트를 남깁니다.
  • 변경 요청이 있을 경우, 수정을 반영한 후 다시 푸시하고 리뷰를 요청합니다.
  • 디자인 변경이 있을 경우, Chromatic을 활용하여 UI Review 단계에서 해당 디자인을 담당한 디자이너에게 리뷰를 요청합니다. (생성된 PR의 하단 Merge 부분에서 확인할 수 있음)
image

UI Review: 작업 내역을 디자인 담당자에게 확인 요청하는 작업

image

UI Tests: 코드 변경으로 발생한 UI 변경이 혹시 UI Regression은 아닌지 Chromatic이 떠준 스냅샷을 하나씩 비교하면서 개발자가 스스로 확인해주는 작업

  • 최소 1개의 승인을 받은 후 main 브랜치에 병합됩니다.
  • 이후 릴리즈를 통해 기여한 내용이 배포됩니다.

프로젝트 구조

  • src/components 아래에 폴더를 만들고, 그 안에 컴포넌트 파일, 스토리 파일, 테스트 파일을 위치시킵니다.
  • 폴더 이름, 파일 이름, 컴포넌트 이름은 모두 PascalCase로 letter case를 통일합니다.
  • 변수 이름, 함수 이름, prop 이름은 모두 camelCase로 letter case를 통일합니다.
  • index.tsx 파일을 통해서 re-export하지 않습니다.
├── src
│   ├── components
│   │   ├── Checkbox
│   │   │   ├── Checkbox.stories.tsx
│   │   │   ├── Checkbox.test.tsx
│   │   │   └── Checkbox.tsx

코드 작성 및 검토

  • 컴포넌트 설계와 구현은 구분해서 Pull Request를 제출합니다. 바람직한 컴포넌트 API에 대한 사전 합의를 진행함으로써 엉뚱한 구현을 방지하기 위함입니다.
  • PR 병합을 하기 위해서는 최소 1명의 동료 개발자로부터 승인을 받아야 하지만, 품질 향상을 위해서 긴급 건이 아니라면 2개의 승인을 받는 것이 권장됩니다.
  • [Proposed] "Resolve conversation" 버튼은 코드 검토자가 피드백이 본인이 의도한 대로 조치되었는지 확인하는 차원에서 누릅니다. 코드 작성자가 임의로 Resolved 표시할 시 불필요한 오해가 생길 수 있습니다.

컴포넌트

  • 함수 컴포넌트 작성할 때는 function 키워드로 선언해주세요.
  • 이벤트 핸들러를 작성할 때는 화살표 함수를 선언 후에 변수에 할당해주세요.
  • Boolean props는 is, has 접두사를 사용하지 않고 형용사 형태로 작성해주세요. (예: reversed)
  • API의 설명을 작성할 때는 명사형태로 작성해주세요 (예: /** 비활성화 상태 */)
  • 신규 컴포넌트 개발시 index.ts에 re-export를 하여 root importimport { button } from "daleui"가 가능하게 해주세요

스토리

  • 스토리 제목이 컴포넌트 경로를 통해서 자동으로 유추될 수 있도록 title 속성의 값은 생략해주세요. 문자열로 직접 명시하면 타입 안전하지 않고, 컴포넌트 이름을 바꿀 때 싱크가 깨지기 쉽습니다.
  • 여러 스토리에 걸쳐서 필요한 args는 스토리 수준에서 중복하지 마시고 컴포넌트 수준에서 지정해주세요.
  • 스토리북은 컴포넌트 함수의 타입에 따라서 알아서 최적의 arg type을 적용해줍니다. 스토리북이 기본으로 설정해준 arg type을 덮어쓰면 컴포넌트의 타입이 변할 때 마다 개발자가 계속 신경써서 arg type을 조정 해줘야하는데 매우 까먹기 쉬운 부분입니다. 따라서 아주 타당한 이유가 있지 않는한 arg type을 직접 지정하는 것은 삼가해주세요.
    • 타당한 이유 예시)
      1. reactNode Type을 사용해서 story에서 따옴표(")를 사용해야할 때 -> control: 'text' 사용
      2. 컴포넌트를 여러개 export하는 compound pattern의 경우 -> argType 사용

테스트

의존성

  • 항상 의존성을 최신 상태로 유지하기 위해서 Dependabot을 코드 저장소에 설정해놓았습니다.
  • Dependabot이 올린 PR을 늦지 않게 검토 및 병합하고 새로운 버전이 일으키는 breaking changes를 대응하는 작업은 팀 개발자 모두의 공동 책임입니다.
  • Dependabot이 올린 PR을 반드시 PR 코멘트를 통해서 Dependabot에게 원하시는 작업을 시켜주세요. 직접 수정하시면 Dependabot은 해당 PR을 더 이상 자동으로 관리해주지 않습니다.

품질 검사

main 브랜치에 품질 기준에 미달하는 코드가 유입이 되지 않도록 PR을 올리시면 자동으로 품질 검사가 진행되고 실패할 경우 병합이 불가능합니다. 각 품질 검사는 개발자가 로컬 환경에서 직접 진행하실 수도 있습니다.

Formatting

Prettier를 통해서 일관적인 코드 포멧팅을 유지하고 있습니다. VSCode 사용자 분들은 Prettier 익스텐션을 쓰시면 코드를 작성하면서 자동으로 코드를 포멧팅할 수 있어서 편하니 추천드립니다.

Prettier options 는 기본 설정값으로 해주시길 바랍니다.

Linting

ESLint를 통해서 잠재적인 문제를 발견하고 모범 사례를 따르고 있습니다. 린팅 규칙을 위반하고 있는 코드가 있는지 확인하려면 다음 명령어를 실행합니다.

$ bun run lint

Type Checking

TypeScirpt를 통해서 정적 타입 검사를 하고 있습니다. 타입 오류가 있는지 확인하려면 다음 명령어를 실행합니다.

$ bunx tsc

npm 패키지 배포 과정

flowchart
    A[main 브랜치]
    B[release/x.y.z 브랜치]
    C["install test<br/>(GitHub Action)"]
    D["태그 생성 &<br/>GitHub Release Draft 생성<br/>(GitHub Action)"]
    F["npm publish 실행<br/>(GitHub Action)"]

    A -->|"release 브랜치 생성<br/>(개발자)"| B
    B -->|"QA / 테스트 및 수정, PR 생성<br/>(개발자)"| C
    C -->|"release → main merge<br/>(개발자)"| D
    D -->|"내용 검토 및 GitHub Release 발행<br/>(개발자)"| F
    F --> A
Loading
Add a custom footer
Add a custom sidebar

Clone this wiki locally