버전 관리 (Versioning)는 별것 아닌 것처럼 보이지만, 문제가 생기기 전까지는 그렇지 않은 일 중 하나입니다. 최근 vibe-coding-universal의 업데이트에서, 저희는 비교 테이블 (comparison tables)의 작지만 지속적인 불편함이었던 "Old Version" 레이블 문제를 해결했습니다. 최신 릴리스 사이클 이후, 이를 구체적으로 v1.0으로 표시하도록 수정했습니다. 이제 사용자들이 릴리스 간의 기능을 비교할 때 더 이상 모호함을 느끼지 않을 것입니다.

문제점: 버전 비교 시의 모호한 레이블

Vibe-coding-universal은 개발자들이 릴리스 간의 기능 차이 (diff)를 빠르게 확인할 수 있도록 일련의 비교 테이블을 유지 관리합니다. 이 테이블들은 문서 (documentation), 인라인 UI 툴팁 (inline UI tooltips), 그리고 CLI의 프리뷰 생성에도 사용됩니다. 원래 이 테이블들은 초기 프로토타이핑 (prototyping) 단계에서 가져온 플레이스홀더 (placeholder)인 "Old Version"이라는 명칭으로 이전 버전을 단순히 표시했습니다.

기능적으로는 작동했지만, 이 레이블은 혼란을 야기했습니다. 사용자가 v1.0을 v0.9와 비교할 때, 어떤 버전이 선택되었느냐에 따라 두 항목이 "Old Version"과 "v1.0"으로 번갈아 표시되었습니다. 더 심각한 것은, 누군가 티켓 (ticket)이나 커밋 메시지 (commit message)에서 이 테이블을 참조할 때, 어떤 "Old Version"이 실제 어떤 릴리스에 해당하는지 해독해야 했다는 점입니다. 해결책은 간단했습니다. 비교 로직 (comparison logic)에서 버전 레이블을 명시적으로 매핑 (map)하는 것이었습니다.

해결책: 테이블 렌더링 시 명시적 버전 매핑

핵심 변경 사항은 테이블 렌더러 (table renderer)에 있었습니다. 기존에는 현재 버전 이전의 모든 릴리스에 대해 기본값으로 "Old Version"을 반환하는 일반적인 version_label 함수에 의존했습니다. 저희는 이를 릴리스 메타데이터 (release metadata)의 구체적인 버전 문자열을 존중하는 룩업 (lookup) 방식으로 교체했습니다.

다음은 풀 리퀘스트 (pull request)의 관련 스니펫 — 테이블 컴포넌트 (table component)의 변환 내용입니다:

// 이전: 모든 이전 버전에 대한 일반적인 레이블
function formatVersionLabel(version, currentVersion) {
  if (version === currentVersion) return currentVersion;
...

releaseMap은 프로젝트의 변경 로그 (changelog)로부터 생성되며, 지원되는 모든 버전에 명확한 레이블을 부여합니다. v1.0 릴리스의 경우, label: "v1.0"을 명시적으로 설정했습니다. 이 변경 사항은 전체 기능 차이 (full feature diff), 나란히 비교하는 API 비교 (side-by-side API comparison), 그리고 플러그인 호환성 매트릭스 (plugin compatibility matrix) 등 세 가지 테이블 뷰 모두에 연쇄적으로 적용되었습니다.

더 이상 추측할 필요가 없습니다. 이제 모든 셀에는 일반적인 범주가 아닌 정확한 버전 식별자가 표시됩니다.

이것이 개발자 대상 도구에 중요한 이유

이는 단순한 외관상의 변경이 아닙니다. 숙련된 개발자에게 비교 테이블의 버전 레이블은 참조 기준점입니다. 업그레이드 여부를 평가할 때, 사용자는 "현재 버전 (Current)"과 "이전 버전 (Old Version)" 사이가 아니라, v0.9와 v1.0 사이에서 정확히 무엇이 변했는지 알아야 합니다. 여기서 발생하는 모호함은 의사결정의 마찰을 높이며, 심지어 다운스트림 프로젝트 (downstream projects)에서 잘못된 의존성 요구 사항 (dependency requirements)을 초래할 수도 있습니다.

Vibe-coding-universal은 로컬 개발 환경을 위한 일련의 반응형 프리셋 (reactive presets)인 "vibe" 설정을 관리하기 위한 내부 도구로 시작되었습니다. 프로젝트가 성장함에 따라, 비교 테이블은 버전 호환성을 이해하기 위한 주요 인터페이스가 되었습니다. "이전 버전 (Old Version)" 레이블은 단 두 개의 버전만 존재했던 초기 단계의 잔재였습니다. v1.0에 도달하고 릴리스 이력이 쌓이면서, 해당 레이블은 더 이상 의미가 없게 되었습니다.

구현 세부 사항 및 하위 호환성 (Backwards Compatibility)

수정 사항은 테이블 렌더링 모듈(src/tables/comparison.js)에 적용되었습니다. 렌더링 함수에 versionLabels 파라미터를 추가했습니다:

function renderComparisonTable(versions, features, versionLabels = {}) {
  return versions.map(version => ({
    version: versionLabels[version] || version,
...

기본 versionLabels 딕셔너리는 모든 툴킷 배포본에 포함된 releases.json 매니페스트 (manifest)를 기반으로 구축됩니다. 이는 자체 비교 테이블을 유지하는 플러그인과 같은 커스텀 배포 (custom deployments)의 경우, 코어 (core)를 포크 (fork)하지 않고도 레이블을 재정의할 수 있음을 의미합니다.

모든 기존 사용 사례는 자동 리팩터링 (automated refactoring)을 통해 업데이트되었으며, 문서 내 모든 비교 테이블 (comparison table)의 알려진 스냅샷 (snapshots)을 대상으로 출력값을 검증했습니다. 테이블 레이아웃이나 데이터 무결성 (data integrity) 측면에서의 회귀 (regressions)는 발생하지 않았습니다.

핵심 요약 (Takeaway): 릴리스 커뮤니케이션에서 디테일의 중요성

레이블을 업데이트하는 것은 사소해 보일 수 있습니다. 하지만 버전 관리 (versioning)는 프로젝트의 성숙도와 안정성을 나타내는 신호입니다. 비교 테이블에 v1.0을 명확하게 표시함으로써, 당사의 툴링 (tooling)을 사용하는 개발자들에게 혼란을 줄 수 있는 요인을 하나 더 줄였습니다. 만약 라이브러리나 프레임워크를 유지 관리하고 있다면, 유사한 플레이스홀더 (placeholders)가 있는지 자체 UI를 점검해 보십시오. 이는 사용자 신뢰에 막대한 영향을 미치면서도 비용은 적게 드는 수정 방법입니다.

Vibe-coding-universal v1.0이 이제 정식 출시되었으며, 비교 테이블에도 해당 내용이 정확히 반영되어 더 이상 "이전 버전 (Old Version)"의 잔재가 남아있지 않습니다. 전체 수정 목록은 변경 로그 (changelog)를 확인하시기 바랍니다. 다만 이번 수정 사항은 문서를 읽거나 플러그인 호환성 (plugin compatibility)을 비교하는 모든 사용자에게 가장 눈에 띄는 변화입니다.