0.x에서 1.0으로 _ 버전 대응 전략

이 책의 예제가 작성된 marimo는 0.23.x입니다. 이 챕터를 읽는 시점에 설치된 marimo는 다를 수 있습니다. 0.x 시리즈는 마이너 버전이 올라갈 때마다 API가 바뀔 수 있습니다. 이 현실을 무시하면 예제 코드가 조용히 깨지고, 원인을 찾는 데 시간을 씁니다. 반대로, 몇 가지 습관만 들여두면 버전 변경이 큰 문제가 되지 않습니다.

왜 0.x인가

시맨틱 버전(SemVer) 관례에서 0.x 시리즈는 아직 안정 API를 선언하지 않은 상태를 의미합니다. 이 범위에서는 마이너 버전 업그레이드(예: 0.22에서 0.23으로)에서도 하위 호환성이 깨지는 변경이 포함될 수 있습니다. SemVer 1.0 이상에서는 메이저 버전이 올라갈 때만 그런 변경이 허용됩니다.

marimo가 1.0을 선언한다면, 그 시점부터 공개 API 변경에 대한 약속이 생기는 것입니다. 그 시점이 언제인지, 어떤 변경이 수반되는지는 공식 릴리스 노트에서 확인해야 합니다. 이 책에서는 특정 일정이나 내용을 단정하지 않습니다.

버전 고정이 출발점이다

PART 01 Ch 02에서 버전 고정을 배웠습니다. 그 습관이 이 챕터 전체의 전제입니다.

# uvuv pip install "marimo==0.23.*"# pippip install "marimo==0.23.*"

0.23.*는 0.23.x 패치 버전 중 최신을 설치하되, 0.24 이상은 설치하지 않는다는 의미입니다. 이 책의 예제를 그대로 실행하려면 이 범위로 고정하는 것이 가장 안전합니다.

정확한 패치 버전까지 고정하려면 설치 후 freeze합니다.

pip freeze | grep marimo# marimo==0.23.10

이 값을 requirements.txt에 기록해두면 팀원 모두가 동일한 버전을 설치합니다.

__generated_with로 노트북 생성 버전 확인하기

marimo 노트북 파일을 텍스트 에디터로 열면 상단에 다음 줄이 있습니다.

__generated_with = "0.23.10"

이 줄은 노트북이 처음 만들어진 marimo 버전을 기록합니다. 다른 사람에게 파일을 받거나, 오래된 파일을 다시 열 때 이 줄을 확인하면 작성 당시 버전을 즉시 알 수 있습니다.

현재 설치된 버전과 다를 때 노트북이 정상 동작하는지는 직접 실행해봐야 압니다. 차이가 크다면 CHANGELOG에서 두 버전 사이의 변경 내역을 확인하는 것이 빠릅니다.

현재 설치된 버전은 다음 명령으로 확인합니다.

marimo --version

0.23.10

릴리스 노트와 CHANGELOG 읽는 방법

버전을 올리기 전에 반드시 릴리스 노트를 확인합니다.

https://github.com/marimo-team/marimo/releases

각 릴리스 항목에서 확인할 것은 두 가지입니다.

첫째, "Breaking changes" 또는 "Migration guide" 항목이 있는지 봅니다. 이 항목이 있으면 기존 코드에 영향을 줄 수 있습니다. 해당 API를 사용하는지 프로젝트 코드에서 검색합니다.

둘째, 사용 중인 기능이 변경되거나 제거됐는지 확인합니다. mo.cache, mo.ui.*, mo.sql(), marimo export, marimo check 같은 이 책에서 다룬 기능들을 중심으로 읽습니다.

CHANGELOG는 릴리스 페이지와 같은 저장소 루트의 CHANGELOG.md에도 있습니다. 여러 버전을 한 번에 건너뛸 때는 CHANGELOG가 릴리스 페이지보다 훑기 편합니다.

marimo check로 업그레이드 후 점검하기

버전을 올린 다음 실행할 첫 번째 명령입니다.

marimo check notebook.py

정적 분석 도구이므로 실행하지 않아도 파일 구조의 문제를 잡습니다. MB002(중복 정의), MB003(순환 의존성) 같은 구조 문제 외에도, 버전 업그레이드 후 새롭게 추가된 규칙이 적용될 수 있습니다.

프로젝트에 노트북이 여러 개라면 반복 실행을 스크립트로 묶습니다.

for f in notebooks/*.py; do    marimo check "$f"done

에러가 없으면 다음 단계로 넘어갑니다. 에러가 있으면 해당 파일과 줄 번호를 확인해 수정합니다.

예제 코드가 새 버전에서 깨질 때

이 책의 예제가 설치된 marimo 버전에서 동작하지 않는 상황이 생길 수 있습니다. 그때 참조할 순서입니다.

첫째, 에러 메시지를 읽습니다. marimo는 대부분 어떤 API가 변경됐는지 에러 메시지나 경고로 알려줍니다.

둘째, 공식 문서를 확인합니다. docs.marimo.io의 API 레퍼런스가 현재 설치된 버전의 실제 동작을 반영합니다. 이 책보다 공식 문서가 항상 우선입니다.

셋째, 릴리스 노트에서 해당 API 변경을 찾습니다. "Breaking changes" 항목에 마이그레이션 방법이 나와 있는 경우가 많습니다.

넷째, 이 책의 GitHub 저장소 Issues를 확인합니다. 이미 같은 문제를 보고하거나 해결한 내용이 있을 수 있습니다.

https://github.com/sung2ne/textbook-marimo/issues

해결하지 못했다면 위 Issues에 새 항목을 남길 수 있습니다.

버전 대응을 습관으로 만들기

정리하면, 네 가지 습관입니다.

이 네 가지가 자리 잡으면, 버전 변경을 두려워하지 않고 적절한 시점에 업그레이드를 결정할 수 있습니다. 버전 고정과 릴리스 노트 확인은 marimo뿐 아니라 0.x 시리즈 라이브러리를 다룰 때 공통으로 적용되는 실천입니다.

정리

• marimo 0.x 시리즈에서는 마이너 버전 업그레이드에서도 API가 바뀔 수 있습니다. 이는 SemVer 0.x의 일반적인 특성입니다.
• 버전 고정(marimo==0.23.*)이 가장 기본적인 대응 수단입니다.
• __generated_with 줄로 노트북이 작성된 버전을 즉시 확인할 수 있습니다.
• 업그레이드 전에는 릴리스 노트의 Breaking changes를, 업그레이드 후에는 marimo check를 실행합니다.
• 예제가 깨졌을 때는 공식 문서(docs.marimo.io)를 먼저 참조합니다.