업무 노트북의 기본 구성을 개선해도 사용자가 직접 적은 셀까지 바꾸고 싶지는 않았다. 오래된 파일이라는 이유만으로 새 문서를 덮으면 개선보다 손실이 커질 수 있다. 나는 자동 생성한 원형을 확실히 알아볼 수 있는 경우에만 올리고 그 외의 문서는 그대로 두는 쪽으로 업그레이드 범위를 좁혔다.

버전 표시 전에 현재 파일을 먼저 읽는다

upgradeNotebook은 처음에 load를 호출한다. manifest와 실제 정의·Python·노트북 소스 hash가 맞는지 확인하는 경로를 먼저 지난다. 그 다음 현재 템플릿 표시를 보고 이미 대상 버전이면 돌아간다. 오래된 번호만 보고 파일을 교체하지 않는다.

템플릿 번호는 기능을 찾는 단서이고 파일 무결성은 내용이 바뀌었는지 보는 근거다. 둘 중 하나로 다른 하나를 대신할 수 없다. 나는 사용자가 고친 문서를 자동 생성 파일이라고 추정하는 첫 번째 오류를 이 경계에서 줄이려 했다. 파일 이름이 inspect.ipynb라는 사실도 교체 권한이 되지 않는다.

원형 판정은 셀 수보다 구체적이다

원래 배포한 래퍼의 셀 수와 각 셀 source를 정확히 비교한다. 설명 셀과 import, 입력 환경변수와 실행 호출, 검증 셀까지 예상 문자열이어야 한다. 이름과 폴더에 맞춰 생성됐던 부분도 원래 형태로 대조한다. 코드가 비슷해 보인다는 유사도 판단으로 통과시키지 않는다.

여기서 셀 수는 품질의 기준이 아니다. 특정 버전에서 배포한 원형을 식별하는 조건이다. 더 긴 노트북이나 다른 구조가 나쁘다는 뜻도 아니다. 사용자가 한 셀을 더하거나 설명을 고쳤다면 자동 교체가 멈추는 것이 이 경로의 목적이다. 변형을 친절하게 추측해 덮는 기능으로 만들지 않았다.

검증된 수정본도 원형과 다르면 건너뛴다

실제 hash가 manifest와 맞더라도 원형 비교가 다르면 함수는 교체하지 않고 돌아간다. 무결성 검사를 통과했다는 것과 자동 생성 원본이라는 것은 다른 조건이기 때문이다. 정상 검토를 거친 사용자 정의 문서가 있어도 새 기본 템플릿에 맞추려고 지울 이유는 없다.

반대로 hash가 맞지 않는 문서는 원형 판단까지 가기 전에 변경 오류가 날 수 있다. 이 경우를 “기존 문서를 새 형식으로 고쳤다”는 성공으로 표현하지 않는다. 나는 교체하지 않은 경우와 교체할 수 없어 검토가 필요한 경우를 구분해 설명해야 한다고 봤다. 둘 다 문서를 지켰더라도 다음 행동은 다르다.

교체 전에 노트북과 manifest를 함께 남긴다

교체 대상이라고 확인되면 versions 아래에 이전 노트북과 manifest를 먼저 복사한다. 새 workbook을 쓴 뒤 현재 hash와 템플릿 표시를 갱신한다. 내용만 백업하고 예전 검증 메타데이터는 잃는 식으로 나누지 않는다. 어떤 파일과 상태가 한 쌍이었는지 남기는 것이다.

교체 중 오류가 나면 원래 노트북과 manifest를 다시 쓰는 복원 경로가 있다. 이것은 복원 시도이며 모든 파일 쓰기가 반드시 성공한다는 보장은 아니다. 여러 파일을 한 번에 바꾸는 완전한 트랜잭션으로 소개하지 않는다. 필요한 경우 실제 남은 파일과 백업을 대조하는 검수가 이어져야 한다.

시험은 수정한 소스가 남는지 확인한다

기존 시험은 생성된 notebook의 job_id 부분을 바꾼 뒤 upgradeNotebook을 요청한다. PROGRAM_CHANGED가 나고 바꾼 소스가 그대로 남는지 확인한다. 새 템플릿에 필요한 입력·준비·실행·결과 셀도 별도로 검사한다. 셀 이름이 보인다는 사실과 원본 보존을 함께 보는 것이다.

이 시험이 모든 사용자 문서 변형과 저장 장애를 전수 검증한 것은 아니다. 이번 집필에서도 원래 프로젝트의 노트북을 실제로 교체하지 않았다. 정확한 원형 비교와 백업·복원 순서는 소스로 읽고, 기존 시험이 직접 확인한 변경 보존은 별도로 설명한다. 새 문서 생성과 현장 문서 마이그레이션을 같은 완료로 부르지 않는다.

기본값을 개선해도 사용자의 작업은 별개다

관리자 화면의 새 기본 레이아웃을 만들 때도 비슷하다. 앞으로 만들 문서의 기본값과 이미 사람이 고친 문서는 다른 소유를 가진다. 최신 버전으로 맞춘다는 말이 그 차이를 지워서는 안 된다. 나는 개선을 적용하지 않는 경계도 기능의 일부라고 생각한다.

기존 문서를 보존하면 새 템플릿을 전부 자동 적용할 수는 없다. 필요한 경우 사람이 차이를 읽고 선택적으로 옮겨야 한다. 그 비용을 숨기지 않고 보관 위치와 판정 이유를 남기는 것이 낫다. 자동 업그레이드는 많은 파일을 빨리 바꾸는 능력보다 바꾸어도 되는 파일을 정확히 고르는 능력에서 시작했다.