호환성: 릴리스가 약속하는 것
Aggrega를 업그레이드하면 기반으로 삼고 있는 여러 영역이 바뀔 수 있습니다. 문서가 작성되는 기준인 스키마, 스크립트가 호출하는 명령과 플래그, AI 어시스턴트가 호출하는 도구, 기록해 두는 오류 코드, 그리고 플러그인을 빌드할 때 사용하는 플러그인 키트입니다. 이 페이지는 각각에 대해 릴리스가 무엇을 변경할 수 있고 무엇을 변경하지 않는지 설명합니다. 이 페이지에서 언급하지 않는 영역에는 해당 영역의 참조 페이지에 명시된 내용 이상의 약속이 없습니다. 마지막 섹션에서는 이 중 하나가 변경되었음을 릴리스가 어디에서 알리는지 설명합니다. 이 페이지의 약속은 0.9.0부터 적용됩니다. 0.9.0 이전의 Releases는 지원되지 않습니다. 허브 레지스트리인 hub.aggrega.ai는 이들을 위해 만들어진 Plugin 버전을 제공하지 않으며, 이들의 컴파일러는 문서가 aggrega.ai/v1beta1을 선언하는 이 레지스트리의 카탈로그를 읽을 수 없습니다.
Aggrega는 0.x.y 버전으로 릴리스됩니다. 패치 릴리스는 마지막 숫자를, 마이너 릴리스는 가운데 숫자를 올립니다. 카탈로그 엔터티 자체의 metadata.version은 별개의 문제입니다 — 작성자가 aggrega lint --pre-publish가 검사하는 버전 증가 기준에 따라 선택하며, 참조가 그중 하나를 선택하는 방법은 버전 해석에서 설명합니다.
스키마
Aggrega가 게시하는 모든 스키마는 하나의 API 버전인 aggrega.ai/v1beta1에 속합니다 — 엔터티 문서가 apiVersion에 선언하는 값입니다. 아래 규칙은 그 각각에 적용됩니다. 엔터티 종류, 플러그인 페이로드, 그리고 워크스페이스 및 기타 스키마(IR, 워크스페이스 구성, 잠금 파일 등)이며, 모두 스키마 참조에 나열되어 있습니다. API 버전은 릴리스 번호와 별개이며, 여러 릴리스가 같은 API 버전을 읽습니다.
v1beta1 내에서 변경될 수 있는 것
하나의 API 버전 내에서 스키마는 Kubernetes가 자체 API 버전을 변경하는 방식과 마찬가지로 추가 방식으로만 변경됩니다. 릴리스는 다음을 할 수 있습니다:
- 설명 변경;
- 필드 추가(해당 필드가 선택 사항인 경우).
이러한 변경 이전에 유효했던 모든 문서는 변경 이후에도 유효하며 같은 의미를 가집니다. IR이나 잠금 파일처럼 컴파일러가 작성하는 문서를 읽는 프로그램은 알지 못하는 필드를 허용해야 합니다. v1beta1 내에서 추가된 선택적 필드가 해당 출력에 나타날 수 있기 때문입니다.
v1beta2가 필요한 것
다음 변경 사항은 각각 새로운 API 버전인 aggrega.ai/v1beta2가 필요합니다:
- 필드 제거 또는 이름 변경;
- 필드를 필수로 만들기;
- 타입 또는 필드가 허용하는 값의 집합 좁히기;
- 값의 의미 변경.
새로운 API 버전은 호환성을 깨는 변경이며, 이를 도입하는 릴리스에서 그러한 변경으로 일정이 잡히고 공지됩니다.
새 선택적 필드는 이를 인식하는 컴파일러와 함께 카탈로그에 도입됩니다
컴파일러는 스키마가 선언하지 않은 필드를 거부합니다. 이러한 엄격함 덕분에 철자가 잘못된 키를 잡아낼 수 있으며, 여기에는 독자가 짐작하기 어려운 결과가 하나 있습니다: 카탈로그 엔터티는 새로 추가된 선택적 필드를, 그 필드를 인식하는 컴파일러를 포함한 릴리스에서만 사용하기 시작할 수 있습니다.
예를 들어, 어떤 릴리스가 Component 스키마에 선택적 필드를 추가한다고 가정하겠습니다 — 이를 spec.newField라고 부르겠습니다:
- 그 릴리스 이전에 작성된 모든 Component는 여전히 유효하며, 그중 어느 것도 해당 필드를 설정하지 않습니다.
- 카탈로그 작성자가
spec.newField를 설정하는 Component의 새 버전을 게시합니다. - 해당 릴리스 또는 그 이후 릴리스의 컴파일러는 그 Component를 검증하고 빌드합니다.
- 그 이전 릴리스의 컴파일러는 자체 스키마가 해당 필드를 선언하지 않으므로 이를 거부합니다. 검증 결과
spec.newField: unexpected property가 보고되고 해당 줄이 표시됩니다.
따라서 해당 카탈로그 버전을 기반으로 빌드하는 사람은 먼저 그 필드를 추가한 릴리스로 업그레이드하고, 카탈로그는 그 릴리스가 나온 뒤에만 해당 필드를 사용하는 엔터티를 게시합니다. 잠긴 Release가 해석한 버전을 어떻게 유지하는지는 버전 해석에 설명되어 있습니다.
명령줄과 어시스턴트 도구
스크립트, CI 파이프라인, 어시스턴트 구성은 aggrega 명령, 플래그, 어시스턴트 도구를 이름으로 호출합니다. 0.x 릴리스에서는 다음과 같습니다:
- 패치 릴리스는 명령, 플래그 또는 어시스턴트 도구를 제거하거나 이름을 바꾸지 않습니다.
- 마이너 릴리스는 이 중 하나를 제거하거나 이름을 바꿀 수 있으며, 해당 변경 로그의 Removed 또는 Changed 아래에 이를 명시합니다.
- 추가 사항 — 새 명령, 플래그 또는 도구 — 은 어떤 릴리스에서든 나올 수 있습니다.
어시스턴트 도구는 aggrega mcp가 연결된 어시스턴트에 제공하는 도구입니다. 서버 자체의 응답이 그 전체 목록이며, 이를 요청하는 방법은 어시스턴트가 Aggrega로 할 수 있는 일에서 설명합니다. 명령을 실행하는 도구는 해당 명령의 호출 경로에서 이름을 가져오므로, 명령의 이름을 바꾸면 그 도구의 이름도 바뀝니다. CLI 개요에는 모든 명령이 나열되어 있습니다.
오류 코드
실행을 중단시키는 모든 조건에는 짧은 코드 — 문자 E와 네 자리 숫자, 예: [DEVELOPER_ERROR E0007] — 가 있으며, 진단의 맨 앞에 출력됩니다. 짧은 코드는 공개 계약입니다: 코드는 한 번만 부여되고, 번호가 다시 매겨지지 않으며, 다른 조건에 부여되지 않습니다. 폐기된 조건의 코드는 폐기된 상태로 유지되므로, 런북, CI 규칙 또는 이슈에 기록된 코드는 업그레이드 후에도 항상 같은 조건을 가리킵니다.
오류 센티널은 조건이 지니는 식별자 — 사람이 인용하는 짧은 코드, 프로그램이 기록하는 설명형 코드, 프로그램이 일치 여부를 확인하는 Go 접근자 — 와, 각각이 무엇을 약속하는지, 그리고 폐기된 번호가 다시 부여되지 않도록 하는 방법을 설명합니다. 그 모든 조건 표는 폐기된 코드를 포함한 모든 짧은 코드를 확인해 주며, aggrega explain은 터미널에서 하나의 코드를 확인해 줍니다.
Plugin 키트
플러그인 개발 키트 — github.com/aggrega-ai/aggrega-pdk/go, aggrega-pdk-rust, @aggrega-ai/aggrega-pdk-typescript — 와 이들이 다시 내보내는 aggrega-abi 코덱은 0.9.0부터 시맨틱 버저닝을 따릅니다. 세 언어의 키트는 하나의 버전 번호를 공유하고, 세 언어의 코덱은 또 다른 버전 번호를 공유합니다.
- 어떤 버전을 기준으로 빌드한 플러그인은 같은 계열의 이후 모든 릴리스를 기준으로도 계속 빌드됩니다.
0.9.x내에서 릴리스는 내보낸 함수, 타입, 상수를 추가할 수 있으며, 이를 제거하거나 변경하지 않습니다. - 내보낸 API에 대한 호환성을 깨는 변경은 새로운 마이너 버전에서만 제공됩니다(
0.9.x에서0.10.0으로). 패치 릴리스는 호환성을 깨지 않습니다. 키트와 코덱은 Aggrega 자체의1.0.0과 함께1.0.0으로 전환되며, 그 이후에는 호환성을 깨는 변경이 메이저 번호를 올립니다. - 코덱의 호환성을 깨는 변경은 키트의 호환성을 깨는 변경이기도 하며, 키트는 코덱 타입을 다시 내보내므로 이와 함께 자체 마이너 버전을 올립니다.
- 기존 타입에 추가된 필드나 멤버가 추가 사항으로 간주되는지는 언어에 따라 다릅니다. 패키지와 함께 게시되는 각 키트의 README는 “Compatibility” 항목에서 해당 언어의 경우를 설명합니다.
이 약속은 플러그인 소스가 참조하는 API에 적용됩니다. 컴파일러와 실행 중인 플러그인 사이를 오가는 것은 대신 플러그인 ABI 버전이 보장합니다: 하나의 ABI 버전 내에서 소켓에는 설명과 선택적 필드만 추가되므로, 이를 기준으로 빌드한 플러그인은 계속 로드됩니다. 플러그인 계약은 소켓을 설명하고, 플러그인 개발자 가이드는 이를 둘러싼 워크플로를 설명합니다.
릴리스의 변경 로그가 알려 주는 것
각 릴리스의 노트는 릴리스 페이지에 있으며, Added, Changed, Removed, Fixed 등의 제목 아래 그룹화된 변경 로그를 담고 있습니다. 이 페이지에서 다루는 영역의 경우:
- 제거되거나 이름이 바뀐 명령, 플래그 또는 어시스턴트 도구는 해당 변경을 수행하는 마이너 릴리스에서 Removed 또는 Changed 아래에 나열됩니다.
- 새 스키마 API 버전은 이를 도입하는 릴리스에서 호환성을 깨는 변경으로 공지됩니다.
- 플러그인 키트 또는 코덱의 호환성을 깨는 변경은 버전 번호에 드러납니다:
1.0.0미만의 새로운 마이너 버전입니다. - 오류 코드는 의미가 결코 바뀌지 않으므로, 이를 공지해야 하는 릴리스는 없습니다.