Conventions

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

프로젝트 설정

로컬 실행 환경 설정

1. Bun 설치하기
2. 리포지토리 관리자에게 초대를 요청하고 권한을 획득한 이후, 리포지토리를 클론합니다.
3. 터미널에서 아래 명령어를 실행합니다:

cd path/to/clone-repo
#  의존성 설치
bun install

# Storybook 실행 (디자인 시스템 기여 시)
bun run sb # or bun run storybook

# 마케팅 웹사이트 실행 (마케팅 웹사이트 기여 시)
bun run dev

코드 기여 가이드

1. 프로젝트 보드에서 To Do 상태의 티켓을 선택하고 본인에게 할당합니다.

2. 프로젝트 설정

   • 먼저 프로젝트 설정 가이드를 완료합니다.

3. 브랜치 생성

   • main 브랜치에서 새로운 feature 브랜치를 생성합니다.
   • 브랜치 이름에는 -, _ 외의 특수문자 사용은 제한됩니다.
     참고 이슈

4. 기능 구현 및 커밋

   • 브랜치 내에서 소스 코드를 수정하고 커밋합니다.
   • 변경이 모두 완료되면 포크받은 리포지토리의 브랜치를 푸시합니다.

5. 테스트 작성

   • 기여한 코드가 정상적으로 동작하는지 확인할 수 있는 테스트 코드를 작성합니다.

6. PR 생성

   • Pull Requests 페이지에서 새로운 PR을 생성합니다.

   • PR이 등록된 이슈와 연관되어 있다면, PR 생성 후 오른쪽 사이드바의 Development 항목에서 해당 이슈를 선택해 연결해주세요.

     

7. PR 리뷰 및 병합

   • 최소 한 명 이상의 관리자가 PR을 검토하고 코멘트를 남깁니다.
   • 변경 요청이 있을 경우, 수정을 반영한 후 다시 푸시하고 리뷰를 요청합니다.
   • 최소 1개의 승인을 받은 후 main 브랜치에 병합됩니다.
   • 이후 릴리즈를 통해 기여한 내용이 배포됩니다.

품질 검사

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

Formatting

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

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

Linting

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

$ bun run lint

Type Checking

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

$ bunx tsc

프로젝트 구조

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

├── src
│   ├── components
│   │   ├── Checkbox
│   │   │   ├── Checkbox.stories.tsx
│   │   │   ├── Checkbox.test.tsx
│   │   │   └── Checkbox.tsx

• 관련 논의: https://github.com/DaleStudy/leaderboard/pull/18#pullrequestreview-2377895806

코드 작성 및 검토

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

컴포넌트

• 함수 컴포넌트 작성할 때는 function 키워드로 선언해주세요.
• 이벤트 핸들러를 작성할 때는 화살표 함수를 선언 후에 변수에 할당해주세요.

스토리

• 스토리 제목이 컴포넌트 경로를 통해서 자동으로 유추될 수 있도록 title 속성의 값은 생략해주세요. 문자열로 직접 명시하면 타입 안전하지 않고, 컴포넌트 이름을 바꿀 때 싱크가 깨지기 쉽습니다.
  • 관련 논의: https://github.com/DaleStudy/daleui/pull/168#discussion_r2048006809
• 여러 스토리에 걸쳐서 필요한 args는 스토리 수준에서 중복하지 마시고 컴포넌트 수준에서 지정해주세요.
  • 관련 논의: https://github.com/DaleStudy/daleui/pull/168#discussion_r2048008436

테스트

• 테스트 파일은 별도의 디렉토리에 중앙화 하지 않고 애플리케이션 파일 바로 옆에 둡니다.
• 단순한 테스트 구조를 위해서 테스트 대상 모듈의 구조가 복잡하지 않다면 describe()-it() 대신에 test()를 씁니다.
• 이벤트를 발생시킬 때는 fireEvent 대신에 @testing-library/user-event 패키지를 사용해 주세요. 브라우저 입장이 아닌 사용자 입장에서 테스트를 작성하기 위함입니다.
  • 관련 논의: https://github.com/DaleStudy/daleui/pull/170#discussion_r2057064150
• 테스트 제목은 한국어 사용자가 쉽게 명세를 파악하기 쉽도록 한글로 작성해주세요.
  • 관련 논의
    • https://github.com/DaleStudy/daleui/pull/168#discussion_r2059342361
    • https://discord.com/channels/775115965964222492/1280152682044063837/1366565616299020288

의존성

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