EmDash 업데이트

이 가이드는 사이트 운영자용입니다. EmDash로 만든 사이트를 운영하며 더 새 릴리스로 옮기려는 사람을 위한 것입니다. emdash 패키지와 @emdash-cms/cloudflare를 다룹니다. 플러그인 패키지는 자체 가이드 사이트의 플러그인 업그레이드가 있고, 자체 컬렉션과 필드 변경은 배포된 사이트 진화에서 다룹니다.

릴리스와 버전 번호

EmDash는 버전 1.0 이전에 릴리스되며, 버전 번호는 두 규칙을 따릅니다.

• 패치 릴리스(예: 0.35.0에서 0.35.1)는 버그 수정과 작은 개선을 담습니다.
• 마이너 릴리스(예: 0.35에서 0.36)는 새 기능과 모든 호환성 깨짐 변경을 담습니다. 호환성 깨짐 변경은 릴리스 항목에 Breaking으로 표시되며, 항목은 당신에게 요구하는 조치를 명시합니다.

emdash와 @emdash-cms/cloudflare는 함께 릴리스되며 하나의 버전 번호를 공유합니다. @emdash-cms/cloudflare는 정확히 일치하는 emdash 버전에 의존하므로 두 패키지를 한 단계로 업데이트하세요. @emdash-cms/plugin-forms 같은 플러그인 패키지는 자체 버전 번호가 있으며 필요한 최소 emdash 버전을 선언합니다.

릴리스 페이지에는 패키지와 버전마다 항목이 하나 있습니다. 업데이트 전에 설치된 버전과 대상 사이의 emdash 항목을 읽고, 사이트가 Cloudflare에서 실행되면 @emdash-cms/cloudflare에 대해서도 같은 범위를 읽으세요.

업데이트하기 전에

복원 가능한 데이터베이스 백업과 별도의 미디어 스토리지 백업을 만드세요. EmDash의 JSON 내보내기는 사이트를 복원할 수 없고, 코어 마이그레이션에는 운영상 실행 취소 단계가 없습니다. 백업과 복구에 각 데이터베이스의 사용 가능한 복구 지점이 설명되어 있습니다.

사이트를 빌드하는 머신의 Node.js 버전과, Node.js 배포의 경우 서버의 버전을 확인하세요. 시작하기에 지원 버전이 있습니다.

패키지 업데이트하기

아래 명령은 pnpm과 Cloudflare 템플릿에서 만든 사이트를 사용합니다. Node.js 배포에서는 @emdash-cms/cloudflare를 빼세요.

배포하고 검증하기

다른 변경과 같은 방식으로 빌드를 배포하세요. 다음 명령은 Cloudflare 사이트를 배포합니다. Node.js 배포에서는 새 빌드로 서버 프로세스를 다시 시작하세요.

pnpm wrangler deploy

기본 런타임 마이그레이션 모드 auto에서는 배포된 사이트가 첫 요청에서 대기 중인 코어 마이그레이션을 적용합니다. 새 코드가 트래픽을 받기 전에 적용하고 이후에 배포된 데이터베이스를 검증하려면 코어 데이터베이스 마이그레이션 관리를 따르세요. 그 emdash migrate --check 명령은 배포된 데이터베이스에 설치된 버전용 대기 또는 알 수 없는 마이그레이션이 있으면 0이 아닌 코드로 종료합니다.

배포 후 관리를 열고, 공개 페이지를 하나 이상 불러오고, 일회용 항목을 편집·게시하고, 일회용 미디어 파일을 업로드·조회하세요. 사이트가 예약 작업이나 sandboxed 플러그인을 쓰면 그 경로도 검증하세요.

특정 릴리스 참고

대부분의 릴리스는 위 단계만으로 충분합니다. 아래 항목은 EmDash가 이미 저장한 데이터를 바꾼 릴리스를 다루며, 언제 당신의 조치가 필요한지 말합니다.

변경됨: 참조 필드가 relation에 바인딩됨

예전 reference 필드는 대상 항목 ID를 컬렉션 테이블의 열에 보관하고, 관리 패널이 설정할 수 없는 필드 옵션으로 대상 컬렉션을 이름 지었습니다.

참조 필드는 이제 relation에 뒷받침된 항목 선택기이며, 링크는 컬렉션 테이블 밖에 있습니다. 업데이트는 대상 컬렉션을 이름 지은 각 참조 필드를 새 relation에 바인딩하고 열의 항목 ID를 링크로 복사하므로, 필드는 선택이 유지된 선택기가 됩니다. 열은 그대로 두고 업데이트는 아무것도 삭제하지 않습니다.

필드가 바인딩되지 않은 채로 남는 경우는 다음과 같습니다.

• 대상 컬렉션을 이름 짓지 않거나, 더 이상 존재하지 않는 것을 이름 짓는 경우
• searchable 또는 indexed로 표시된 경우
• relation 슬러그 {collection}_{field}가 필요한데 그 슬러그가 이미 쓰인 경우
• 같은 항목의 서로 다른 로케일에서 다른 항목을 선택하는 경우(어떤 항목에서든)

마지막은 링크가 어디에 있는지에 관한 것입니다. 링크는 항목의 번역 그룹에 속하므로 하나의 선택이 모든 번역에 공유되고, 예전 열은 로케일별이었습니다. 로케일이 서로 다른 필드에는 옮길 단일 선택이 없습니다 — 병합하면 각 로케일에 다른 쪽의 항목을 주고, 한 로케일의 답을 고르면 나머지를 버립니다 — 그래서 업데이트는 필드를 그대로 두고 두 값을 열에서 읽을 수 있게 둡니다.

불일치처럼 보이는 두 경우는 그렇지 않습니다. 한 항목의 자체 번역을 이름 짓는 로케일은 그 항목을 한 번 선택한 것이므로, 업데이트는 필드를 바인딩하고 링크는 각 로케일 자체 버전으로 해석됩니다. 아무것도 선택하지 않은 로케일은 다른 로케일과 모순되지 않으므로 업데이트는 필드를 바인딩하고 그룹의 한 선택이 빈 것을 포함한 모든 번역에 적용됩니다.

바인딩되지 않은 필드는 이전과 같이 동작합니다. 열은 항목 ID를 갖고, 값은 저장·로드되며, 필드는 계속 인덱싱되고 콘텐츠 목록 필터로 쓰일 수 있습니다. 항목 편집기에서는 선택기가 아니라 텍스트 상자로 렌더링됩니다.

무엇을 해야 하나요?

참조 필드가 있는 각 컬렉션에서 항목을 여세요. 선택기로 렌더링되는 필드는 아무것도 필요 없습니다. 아직 텍스트 상자로 렌더링되는 필드는 relation을 만들고 필드의 저장된 ID를 링크로 복사하는 relation이 없는 필드 바인딩을 따르세요. 다중 로케일 사이트에서는 바인딩이 모두에 대해 하나의 선택을 유지하므로, 바인딩 전에 각 번역이 가리켜야 할 항목을 정하세요.

업데이트 후 사이트가 깨진 경우

• 빌드가 실패하거나 자체 페이지가 런타임에 오류: 건너뛴 버전의 Breaking 표시 릴리스 항목을 읽고 명시된 변경을 하세요.
• 플러그인이 로드되지 않음: 플러그인 자체 릴리스 항목과 사이트의 플러그인 업그레이드를 읽으세요.
• 오류가 Astro API 또는 @astrojs/* 패키지를 이름 지음: EmDash는 Astro 6 이상이 필요합니다. Astro의 업그레이드 가이드가 astro와 공식 통합을 함께 업데이트하는 방법을 설명합니다.
• 이전 릴리스로 돌아가려면 일치하는 이전 패키지 버전을 재설치하고 그 아티팩트를 다시 배포하세요. 재설치는 코어 마이그레이션을 되돌리지 않습니다. 이전 아티팩트가 마이그레이션된 데이터베이스를 쓸 수 없으면 트래픽을 멈추고 업데이트 전 데이터베이스와 아티팩트를 함께 복원하세요. 업데이트가 미디어를 바꿨을 때만 미디어를 복원하세요.