EmDash 업데이트

이 가이드는 사이트 운영자를 위한 것입니다. EmDash로 구축한 사이트를 운영하며 더 최신 릴리스로 올리려는 사람을 대상으로 합니다. 업데이터는 프로젝트의 모든 직접 emdash 및 @emdash-cms/* 의존성을 다룹니다. 사용자가 만든 컬렉션과 필드의 변경 사항은 배포된 사이트의 스키마 진화시키기에서 다룹니다.

릴리스 호환성

EmDash는 유의적 버전(semantic versioning)을 따릅니다.

• 패치 릴리스에는 하위 호환되는 수정과 작은 개선 사항이 포함됩니다.
• 마이너 릴리스에는 하위 호환되는 기능이 포함됩니다.
• 메이저 릴리스는 기존 프로젝트의 변경을 요구할 수 있습니다. 해당 릴리스 항목에는 영향을 받는 프로젝트와 필요한 조치가 명시됩니다.

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

릴리스 페이지에는 패키지와 버전마다 하나의 항목이 있습니다. upgrade-emdash는 각 직접 패키지의 변경 로그 범위를 정확한 GitHub 릴리스 태그에서 가져옵니다. 자동 생성된 의존성 업데이트 항목은 제거하고, 직접 작성된 메이저, 마이너, 패치 항목은 전체를 그대로 유지하며, 여러 패키지에 반복되는 항목은 중복을 제거합니다.

템플릿 파일은 업데이트되지 않습니다

템플릿으로 사이트를 만들면 레이아웃, 컴포넌트, 스타일, astro.config.mjs 같은 템플릿 파일이 프로젝트에 복사됩니다. 업데이터는 직접 EmDash 의존성을 변경하고 EmDash 에이전트 스킬을 새로 고칩니다. 사이트의 애플리케이션 파일과 구성 파일은 건드리지 않으며, 프로젝트 소유자나 에이전트가 업그레이드 작업 지시서에 따라 변경합니다. 이후 템플릿에 생긴 변경 사항은 새 사이트에만 적용됩니다. 기존 사이트에 반영하려면 자신의 파일을 templates 디렉터리의 현재 버전과 비교하고 원하는 변경 사항을 복사하세요.

업데이트하기 전에

업데이터는 사이트의 데이터베이스에 연결하지 않고 프로젝트 파일과 설치된 패키지를 변경하므로, 실행 전에 업그레이드 전용 백업이 필요하지 않습니다. 설치 후 .emdash/UPGRADE.md에 추가된 코어 마이그레이션이 있으면 표시됩니다.

업그레이드된 애플리케이션을 시작하거나 배포하기 전에, 작업 지시서에 추가된 마이그레이션이 나열되어 있거나, emdash migrate --status가 이전의 보류 중인 마이그레이션을 보고하거나, 릴리스 항목이 데이터를 변경하는 프로젝트 조치를 요구하면 복구 지점을 만드세요. 구성된 데이터베이스에 대해서는 백업 및 복구를 따르세요. EmDash의 JSON 백업으로는 사이트를 복원할 수 없습니다.

업데이터는 emdash 0.35.0 이상이 필요합니다. 0.35.0은 코어 마이그레이션을 보고하는 첫 릴리스입니다. 더 오래된 사이트는 복구 지점을 만들고, 프로젝트의 패키지 관리자로 emdash와 나머지 직접 @emdash-cms/* 패키지를 0.35.0으로 업데이트한 다음, 해당 릴리스까지의 패키지 변경 로그를 검토하세요. 그런 다음 나머지 업데이트를 위해 업데이터를 실행합니다.

업데이터는 node_modules에서 패키지를 읽으므로 Yarn Plug’n’Play 설치를 지원하지 않습니다. Plug’n’Play를 사용하는 Yarn 프로젝트라면 .yarnrc.yml에 nodeLinker: node-modules를 설정하고 yarn install을 실행한 뒤 업데이터를 실행하세요.

사이트를 빌드하는 머신의 Node.js 버전을 확인하고, Node.js 배포라면 서버의 버전도 확인하세요. 지원되는 버전은 첫 EmDash 사이트 만들기에 나와 있습니다.

업데이트 계획 및 적용

사이트의 프로젝트 디렉터리에서 업데이터를 실행하세요. 업데이터는 설치된 패키지 버전과 코어 마이그레이션 식별 정보를 읽은 다음, 선택한 npm dist-tag를 직접 EmDash 패키지마다 따로 해석합니다. 기본 태그는 latest이며, --to next, --to beta 또는 다른 dist-tag로 릴리스 채널을 선택할 수 있습니다. --to는 정확한 버전을 받지 않습니다.

배포하고 검증하기

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

pnpm wrangler deploy

기본 런타임 마이그레이션 모드인 auto에서는 배포된 사이트가 첫 번째 요청에서 보류 중인 코어 마이그레이션을 적용합니다. 필요한 복구 지점이 마련될 때까지 보류 중인 마이그레이션이 있는 빌드를 배포하지 마세요. 새 코드가 트래픽을 받기 전에 마이그레이션을 적용하고, 이후 배포된 데이터베이스를 검증하려면 코어 데이터베이스 마이그레이션 관리를 따르세요. 해당 문서의 emdash migrate --check 명령은 배포된 데이터베이스에 설치된 버전에 대한 보류 중이거나 알 수 없는 마이그레이션이 있으면 0이 아닌 코드로 종료됩니다.

배포 후에는 관리자를 열고, 공개 페이지를 하나 이상 로드하고, 임시 항목을 편집하여 게시하고, 임시 미디어 파일을 업로드한 뒤 가져와 보세요. 사이트가 예약 작업이나 샌드박스된 플러그인을 사용한다면 해당 경로도 검증하세요.

특정 릴리스 참고

대부분의 릴리스는 위 단계 외에 아무것도 필요하지 않습니다. 아래 항목은 EmDash가 이미 저장한 데이터를 변경한 릴리스를 다루며, 사용자의 조치가 필요한 경우를 알려 줍니다.

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

reference 필드는 예전에는 대상 항목의 ID를 해당 컬렉션 테이블의 열에 저장했고, 관리자 패널에서 설정할 수 없는 필드 옵션에 대상 컬렉션을 지정했습니다.

참조 필드는 이제 관계로 뒷받침되는 항목 선택기이며, 해당 링크는 컬렉션 테이블 밖에 저장됩니다. 업데이트하면 대상 컬렉션을 지정했던 각 참조 필드가 새 관계에 바인딩되고 그 열에 있는 항목 ID가 링크로 복사되므로, 필드는 선택 내용이 그대로인 선택기가 됩니다. 열은 그대로 남아 있으며 업데이트는 아무것도 삭제하지 않습니다.

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

• 대상 컬렉션을 지정하지 않았거나, 더 이상 존재하지 않는 컬렉션을 지정한 경우
• 검색 가능 또는 인덱싱 대상으로 표시된 경우
• 관계 슬러그 {collection}_{field}가 필요한데 해당 슬러그가 이미 사용 중인 경우
• 같은 항목의 서로 다른 로케일에서 서로 다른 항목을 선택한 경우(어떤 항목이든 해당)

마지막 조건은 링크가 저장되는 위치와 관련이 있습니다. 링크는 항목의 번역 그룹에 속하므로 하나의 선택이 모든 번역에서 공유되지만, 이전 열은 로케일별이었습니다. 로케일 간에 값이 다른 필드에는 이어받을 단일 선택이 없습니다. 이를 병합하면 각 로케일에 다른 로케일의 항목을 넘겨주게 되고, 한 로케일의 답을 고르면 나머지가 버려집니다. 그래서 업데이트는 해당 필드를 그대로 두고 두 값을 모두 열에서 읽을 수 있게 남겨 둡니다.

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

바인딩되지 않은 필드는 이전과 같이 동작합니다. 해당 열에는 항목 ID가 들어 있고, 값은 저장되고 로드되며, 필드는 계속 인덱싱하거나 콘텐츠 목록 필터로 사용할 수 있습니다. 항목 편집기에서는 선택기가 아닌 텍스트 상자로 표시됩니다.

무엇을 해야 하나요?

참조 필드가 있는 각 컬렉션에서 항목을 하나 엽니다. 선택기로 표시되는 필드는 아무 조치도 필요하지 않습니다. 여전히 텍스트 상자로 표시되는 필드는 관계가 없는 필드 묶기를 따르세요. 이 절차는 관계를 만들고 필드에 저장된 ID를 링크로 복사합니다. 여러 로케일을 쓰는 사이트에서는 바인딩하면 모든 번역에 대해 하나의 선택이 유지되므로, 바인딩하기 전에 각 번역이 어떤 항목을 가리켜야 하는지 정하세요.

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

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