Breaking Change가 의미하는 것

이런 상황일 때

릴리스 노트 맨 위에 “Breaking Changes” 라는 항목이 있습니다. 아래 목록을 읽어도 그게 나한테 해당되는 이야기인지 알 수가 없습니다. 그냥 올렸다가 안 켜지면 곤란한데 말입니다.

한 줄 결론

깨지는 변경은 세 가지 모습으로 옵니다 — 설정 형식이 바뀌거나, 주고받는 방식이 바뀌거나, 저장 형식이 바뀝니다. 앞의 둘은 고치면 되고 마지막 하나는 되돌릴 수 없습니다.

핵심 개념

① 설정 형식이 바뀐다

쓰던 항목 이름이 없어지거나 적는 방식이 달라집니다. 증상은 대개 “켜지지 않음”이고, 고치기는 가장 쉽습니다. 설정 파일을 고쳐 다시 띄우면 됩니다.

② 주고받는 방식이 바뀐다

다른 프로그램이 이것을 부르는 방법이 달라집니다. 이 프로그램은 멀쩡히 도는데 연결된 쪽이 깨집니다. 그래서 알아채기가 가장 어렵습니다.

③ 저장 형식이 바뀐다

올라가면서 데이터가 새 형식으로 변환됩니다. 이것만은 되돌릴 수 없습니다. 이미지 판을 내려도 데이터가 이미 바뀌어 있어 이전 판이 읽지 못합니다.

적혀 있지 않은 깨짐도 있다

만드는 쪽이 깨진 줄 모르고 낸 경우입니다. 그래서 “Breaking Changes 항목이 비어 있다”가 “안 깨진다”는 보장은 아닙니다.

메이저가 아니어도 깨질 수 있다

약속은 약속일 뿐입니다. 0.x 판이거나 규모가 작은 프로젝트에서는 가운데 자리에서도 깨집니다.

이런 분에게 해당됩니다

• 컨테이너로 여러 서비스를 엮어 쓰는 분
• 메이저 업데이트를 앞두고 무엇을 미리 봐야 할지 찾는 분
• 다른 프로그램이 붙어 있는 서비스를 운영하는 분

확인해야 할 항목

• 설정 파일에서 쓰는 항목이 없어지거나 이름이 바뀌었는가
• 이 프로그램을 부르는 다른 프로그램이 있는가
• 데이터 변환이 일어난다고 적혀 있는가
• 변환이 일어난다면 되돌리는 방법이 있는가
• 건너뛰는 판에도 같은 항목이 있는가

잘못 이해하기 쉬운 부분

안전한 행동 순서

1. 릴리스 노트의 Breaking Changes 항목을 먼저 읽습니다.
2. 항목마다 셋 중 어느 쪽인지 표시합니다 — 설정 / 연동 / 저장.
3. 설정이면 지금 쓰는 설정 파일에서 해당 항목을 찾아 둡니다.
4. 연동이면 이 프로그램을 부르는 것들의 목록을 만듭니다.
5. 저장 형식이면 올리기 전에 백업을 뜨고, 되돌릴 수 없다는 것을 전제로 날을 잡습니다.
6. 여러 판을 건너뛴다면 건너뛰는 모든 판에서 같은 작업을 합니다.

확인 체크리스트

• Breaking Changes 항목을 읽었다
• 각 항목을 설정/연동/저장으로 나눴다
• 설정 파일에서 해당 항목을 확인했다
• 이 프로그램을 부르는 다른 프로그램을 확인했다
• 저장 형식이 바뀐다면 백업을 뜨고 날을 잡았다

관련 도구와 버전 페이지

• 릴리스 이력
  카테고리별 버전 페이지에서 앞자리가 바뀐 지점을 찾을 수 있습니다. 깨지는 변경이 있었다면 대개 거기입니다.
• 호환성 문제 판정 — 아직 제공하지 않습니다
  어떤 판에서 무엇이 깨지는지 이 사이트는 아직 판정하지 못합니다. 각 제품의 릴리스 노트를 직접 보셔야 합니다.

자주 묻는 것

Breaking Changes 가 열 개도 넘습니다.

대부분은 내가 안 쓰는 기능일 가능성이 큽니다. 목록을 다 이해하려 하지 말고 내 설정 파일에 있는 낱말로 훑어보세요. 걸리는 것만 보면 됩니다.

Docker Compose v1 에서 v2 로 넘어갈 때가 그런 경우였나요?

대표적인 예입니다. 명령 이름이 docker-compose 에서 docker compose 로 바뀌었고, 이걸 부르던 스크립트와 cron 이 조용히 안 돌게 됐습니다. 위의 ② 연동 쪽 사례입니다.

저장 형식이 바뀌는지 어떻게 아나요?

릴리스 노트에서 migration, schema, upgrade 같은 낱말을 찾습니다. 그리고 “한 판씩 올리라”는 안내가 있으면 대개 저장 형식이 바뀌는 경우입니다.