본문으로 건너뛰기

릴리스 프로세스

도큐사우루스에서 버전 관리, 릴리스, 주요 변경 사항을 처리하는 방법을 살펴보겠습니다.

정보

이번 주제는 고도로 사용자 정의된 사이트의 업그레이드가 어려운 상황에서 특히 중요한 내용을 담고 있습니다.

유의적 버전 관리​

도큐사우루스의 버전 관리는 major.minor.patch 체계를 기반으로 하며 유의적 버전 관리를 따릅니다.

유의적 버전 관리를 따르는 것은 여러 가지 이유로 중요합니다.

  • public API만 사용했다면 간단한 마이너 업그레이드를 보장합니다.
  • 프론트엔드 생태계 규칙을 따릅니다.
  • 새로운 메이저 버전은 주요 변경 사항을 완벽하게 문서화할 수 있는 기회입니다.
  • 새로운 메이저/마이너 버전은 블로그 게시물을 통해 새로운 기능을 전달할 수 있는 기회입니다.
노트

도큐사우루스 2.0을 릴리스하기까지 꽤 많은 시간이 걸렸습니다. 이제부터 도큐사우루스는 새로운 메이저 버전을 정기적으로 릴리스할 겁니다. 2~4개월마다 새로운 메이저 버전을 기대할 수 있습니다.

메이저 버전 숫자 자체가 신성한 영역은 아니지만 너무 잦은 메이저 버전 릴리스를 방지하기 위해 변경 사항의 유형을 구분해놓았습니다.

메이저 버전​

major 버전 번호는 모든 주요 변경 사항 시 증가합니다.

새로운 메이저 버전이 릴리스될 때마다 우리는 다음 정보과 같은 정보를 제공합니다.

  • 새로운 기능, 수정된 버그, 주요 변경 사항, 업그레이드 지침을 담은 블로그 게시물
  • 빠짐 없이 정리한 변경 기록
팁

우리가 주요 변경 사항으로 여기는 사항을 명확하게 이해하려면 드러난 public API 항목을 참고하세요.

마이너 버전​

minor 버전 번호는 하위 호환성을 유지하는 모든 눈에 띄는 변경 시 증가합니다.

새로운 마이너 버전이 릴리스될 때마다 우리는 다음 정보과 같은 정보를 제공합니다.

  • 새로운 기능, 수정된 버그 목록을 담은 블로그 게시물
  • 빠짐 없이 정리한 변경 기록
팁

드러난 public API만 사용했다면 즉시 업그레이드할 수 있습니다!

패치 버전​

patch 버전 번호는 버그 수정 릴리스 시 증가합니다.

새로운 패치 버전이 릴리스될 때마다 우리는 다음 정보과 같은 정보를 제공합니다.

  • 빠짐 없이 정리한 변경 기록

버전 관리​

도큐사우루스 팀은 일반적으로 동시에 2개 메이저 버전을 작업합니다.

  • 도큐사우루스 2: docusaurus-v2 브랜치의 stable 버전
  • 도큐사우루스 3: main 브랜치의 next 버전
노트

docusaurus-v2 브랜치는 첫 번째 v2 릴리스 후보를 릴리스하기 직전에 생성됩니다.

Stable 버전​

stable 버전(docusaurus-v2 브랜치의 v2)은 대부분 도큐사우루스 사용자에게 적합합니다.

우리는 정기적으로 하위 호환 기능, 버그, 보안 수정 사항을 main에서 docusaurus-v2로 git cherry-pick 명령을 사용해 백포팅해서 next 버전을 사용할 준비가 되지 않은 사용자가 해당 기능을 사용할 수 있게 합니다.

정보

새로운 stable 버전이 릴리스된 이후 이전 stable 버전은 3개월 동안 주요 보안 문제에 대해서만 계속 지원합니다. 그 외의 경우에는 모든 기능 수정은 중지되고 주요하지 않은 버그는 수정하지 않습니다.

해당 기간 내에 새로운 stable 버전으로 업그레이드하는 것을 권장합니다.

Next 버전​

next 버전(main 브랜치의 v3)은 도큐사우루스 팀이 현재 작업하고 있는 버전입니다.

main 브랜치는 코어 팀과 외부 기여자를 포함한 모든 풀 리퀘스트에 대한 기본 대상 브랜치입니다.

이 버전은 최신의 도큐사우루스 기능을 가장 먼저 사용하고자 하는 얼리 어답터에게 권장됩니다. 또한 버그를 보고하거나 피드백을 통해 우리에게 도움이 되는 방법이기도 합니다.

3가지 방법을 통해 next 버전을 사용할 수 있습니다.

  • alpha, beta, rc 사전 릴리스 사용
  • npm 배포 태그 @next을 사용해 최신 사전 릴리스 사용
  • 가장 최신 기능이 반영된 카나리 릴리스 사용
팁

next 버전은 모든 자동화 테스트를 통과했으며 도큐사우루스 사이트에서도 사용하고 있습니다. 어느 정도 안정적인 버전입니다. 시도해보는 것을 두려워하지는 마세요.

warning

next 버전에서 주요 변경 사항이 생길 수 있습니다. 자세한 업그레이드 지침은 변경 기록과 풀 리퀘스트에서 확인할 수 있습니다.

beta와 rc(release candidate) 단계에서는 주요 변경 사항이 발생하지 않도록 하고 있습니다.

드러난 Public API​

도큐사우루스는 유의적 버전 관리를 따릅니다. 도큐사우루스 public API에 변경 사항이 발생하고 이전 버전과 호환성이 중단되면 major 버전 번호를 증가합니다.

팁

도큐사우루스는 minor 버전 간에 public API에 대한 하위 호환성을 보장합니다. 내부 API를 건드리지 않은 상태라면 minor 버전 간 업그레이드는 어렵지 않게 되어 있습니다.

드러난 public API에는 어떤 항목이 있는지 간략하게 설명합니다.

코어 public API​

✅ public API에는 아래 항목이 포함되어 있습니다.

  • 도큐사우루스 config
  • 도큐사우루스 클라이언트 API
  • 도큐사우루스 CLI
  • 프리셋 옵션
  • 플러그인 옵션
  • 플러그인 수명주기 API
  • 테마 config
  • 코어 플러그인 라우트 컴포넌트 속성
  • @docusaurus/types 타입스크립트 타입
    • 우리는 여전히 타입을 더 엄격하게 만들 자유를 유지합니다(타입 체크가 중단될 수 있습니다).
팁

테마 API를 제외하고 문서화된 모든 API는 public으로 간주됩니다(또한 안정적입니다). 문서화되지 않은 API는 내부에서만 사용할 수 있는 것으로 간주됩니다.

API가 "안정적(stable)"이라는 것은 다른 변경 없이 도큐사우루스를 패치 또는 마이너 버전으로 설치할 때 docusaurus start 또는 docusaurus build 명령 실행 시 오류가 발생하지 않아야 함을 의미합니다.

테마 public API​

도큐사우루스는 매우 유연한 테마 시스템을 지원합니다.

  • 사용자 지정 CSS를 사용할 수 있습니다.
  • 어떤 리액트 테마 컴포넌트든 스위즐할 수 있습니다.

이런 시스템 형태로 인해 매우 커다란 API를 암시적으로 드러내고 있습니다. 도큐사우루스가 빠르게 성장하고 향상될 수 있게 이에 대한 하위 호환성은 보장하지 않습니다.

✅ 테마 public API에는 아래 항목이 포함되어 있습니다.

팁

public API만으로 여러분의 사이트를 원하는 형태로 만들지 못할 수 있습니다.

그런 경우에는 여러분이 원하는 사용자 지정 사례를 알려주세요. public API를 확장하는 방법을 고민해보겠습니다.

❌ 테마 public API에는 다음 항목을 제외합니다.

  • DOM 구조
  • 해시 접미사를 가진 CSS 모듈 클래스 이름(일반적으로 [class*='myClassName'] 선택자의 대상이 됩니다)
  • 안전하지 않거나 스위즐할 수 없는 리액트 컴포넌트
  • @docusaurus/theme-common/internal에서 가져오는 리액트 컴포넌트
  • 테마에서 시각적 요소를 담당하는 부분
노트

안전한 컴포넌트를 스위즐링할 때 @docusaurus/theme-common(/internal 하위 경로는 제외하고)에서 문서화되지 않은 API를 가져오는 컴포넌트를 만날 수 있습니다.

해당 API에 대한 하위 호환성을 지원하지만(때문에 "안전한" 것으로 표시됩니다) 직접 사용하는 것을 권장하지는 않습니다.