Enriched Markdown의 사용자 지정 스포일러 공개를 보여주는 호그와트 주문서

핵심 요약

1. enriched-markdown-ios는 아직 1.0 이전 버전이므로, 버전 간 API 변경이나 기본값 조정, 요소 이동이 발생할 수 있다.
2. 0.x 버전에서는 마이너 버전 업데이트만으로도 빌드가 깨질 수 있어, 일반적인 from: 대신 마이너 버전 범위 제한이나 정확한 버전 고정을 권장한다.
3. 문서는 현재 릴리스에 맞춰 수동으로 관리되지만 코드와 차이가 생길 수 있으므로, 컴파일러 동작과 맞지 않는 페이지는 해당 페이지를 명시해 이슈로 보고해야 한다.

도입

Enriched Markdown의 iOS 패키지인 enriched-markdown-ios는 아직 1.0에 도달하지 않았다. 이 단계에서는 버전이 바뀌면서 modifier 이름, 기본값, 지원 요소가 달라질 수 있다. 특히 0.x 버전은 마이너 업데이트에서도 빌드가 깨질 수 있으므로 패키지 의존성 범위를 신중하게 지정해야 한다.

상세 요약

패키지 버전과 API 안정성

enriched-markdown-ios는 아직 1.0 이전 버전이다. 안정 버전에 도달하기 전까지 버전 사이에 API가 바뀔 수 있다. modifier 이름이 변경되거나 기본값이 조정될 수 있고, 지원되는 요소가 이동할 수도 있다. 따라서 현재 코드가 다음 버전에서도 그대로 빌드된다고 가정할 수 없다.

특히 0.x 버전에서는 마이너 버전 번호가 올라가는 업데이트도 빌드를 깨뜨릴 수 있다. 패키지 의존성을 설정할 때 일반적인 from:을 사용하는 대신 다음 중 하나를 선택하도록 안내한다.

• .upToNextMinor(from:)를 사용해 의존성 범위를 마이너 버전 이내로 제한한다.
• .package(url:, exact:)를 사용해 특정 버전을 정확히 고정한다.

업그레이드 전에는 Breaking changes 항목을 확인한다. 이 확인은 버전 변경에 따른 API 차이를 파악하는 절차로 제시되어 있다.

문서와 코드가 다를 때

문서는 현재 릴리스 기준으로 작성되며, 코드 변경에 맞춰 수동으로 관리된다. 따라서 문서가 실제 코드보다 뒤처질 수 있다. 문서의 예시나 설명이 컴파일러가 알려주는 내용과 맞지 않으면, 해당 페이지를 명시해 이슈를 제출한다. 보고할 때는 어떤 페이지에서 차이가 발생했는지 밝혀야 한다.

관련 자료

네이티브 Markdown 렌더링 도구의 다른 사례로는 MarkdownEngine: TextKit 2 기반의 macOS용 네이티브 마크다운 에디터 엔진이 있다.

결론

의존성은 .upToNextMinor(from:)로 제한하거나 .package(url:, exact:)로 버전을 고정하고, 업그레이드 전에 Breaking changes를 확인한다. 문서는 현재 릴리스에 맞춰 수동으로 갱신되므로 코드와 내용이 다를 수 있다. 컴파일러 결과와 맞지 않는 문서를 발견하면 해당 페이지를 밝혀 이슈로 보고한다.