변경 로그 및 버전 관리

버전 관리 정책

ObjectOS는 **유의적 버전(Semantic Versioning)**을 따릅니다: MAJOR.MINOR.PATCH.

모든 @objectstack/* 패키지는 동기화된 버전 번호로 함께 릴리스됩니다 — 개별적으로가 아니라 매트릭스로 테스트됩니다.

호환성 매트릭스

지원 기간

중대한 보안 수정은 현재 및 이전 메이저 버전에 백포트됩니다. 그 외 모든 것은 main에 반영됩니다.

릴리스 노트

릴리스된 ObjectOS 버전과 해당 CHANGELOG 항목은 다음에서 게시됩니다:

• npm: @objectstack/runtime
• GitHub: github.com/objectstack-ai/objectos/releases
• 소스 CHANGELOG: CHANGELOG.md
• 상세 릴리스 노트: RELEASE_NOTES.md

알림을 받으려면 GitHub에서 릴리스를 구독하세요.

주요 변경 사항

10.x — 현재 릴리스 트레인

ObjectOS One과 번들 서버는 이제 @objectstack 10.2.0 기반으로 동작합니다. 메이저 버전 증가에도 불구하고 런타임 부트 계약은 변경되지 않았습니다 — createStandaloneStack은 여전히 동일한 아티팩트, 환경, 데이터베이스 설정을 받으며, 모든 호환성 깨짐 변경은 멀티 조직 테넌시 계층에서 발생하므로 단일 테넌트 ObjectOS 배포(기본값)는 구성 변경 없이 9.x에서 그대로 업데이트됩니다. 바뀐 것은 다음과 같습니다:

• 행 단위 조직 스코핑이 자체 플러그인으로 분리되었습니다 (10.0, 호환성 깨짐) — organization_id 자동 스탬프, 조직별 시드 재생, 기본 조직 부트스트랩이 @objectstack/plugin-security에서 빠져나와 옵트인 방식의 @objectstack/plugin-org-scoping으로 이동했습니다. 단일 조직 배포는 더 가벼워지며(모든 쿼리에서 제거할 와일드카드 RLS가 없음), OS_MULTI_TENANT=true는 여전히 plugin-security보다 먼저 플러그인을 자동 등록하므로 CLI로 구동되는 프로젝트는 코드 변경이 필요 없습니다. ADR-0002에 따르면 테넌트는 물리적 격리(하나의 Environment = 하나의 데이터베이스)이고, organization_id는 하나의 DB 내에서의 논리적 스코핑이므로 자체 플러그인을 가질 자격이 있습니다.
• 자동 개인 워크스페이스가 더 이상 없습니다 (10.0, 호환성 깨짐) — plugin-security는 더 이상 모든 신규 사용자에 대해 "<User>'s Workspace" 조직을 생성하지 않습니다. 사용자는 이제 초대를 수락하거나 명시적으로 첫 조직을 생성합니다 (Slack / Linear / GitHub-Orgs 모델). 첫 등록 사용자 — 플랫폼 관리자로 자동 승격됨 — 는 멀티 테넌트 모드에서 세션이 RLS를 해석할 수 있도록 여전히 단일 Default Organization을 받습니다. 단일 테넌트 배포는 조직을 생성하지 않습니다.
• record 폼 필드 타입 (ADR-0014) — Record<string, X> 속성(예: 객체의 fields 맵)이 이제 Studio에서 원시 JSON으로 새어 나가는 대신 일급 폼 필드로 편집 가능하며, 객체 미리보기 창은 실제 ObjectGrid 렌더러를 마운트합니다 — 미리 보는 것이 곧 출시되는 것입니다.
• IEmbedder를 통한 플러그형 임베딩 — 새로운 임베더 프로토콜과 @objectstack/embedder-openai; 지식 / RAG 어댑터는 이제 IEmbedder를 사용하며 plugin- 접두사를 떼도록 이름이 변경되었습니다.
• Public Forms — /f/:slug에서 제공되는 익명 Web-to-Lead / Web-to-Case 폼, 통합 FormPage(공개 /f/:slug + 내부 /forms/:name), type: 'form' 액션 변형, 그리고 ObjectSchema의 defaultDetailForm.
• 클라우드 아이덴티티 분리 — os cloud login이 이제 os login과 분리되었고, 클라우드 컨트롤 플레인은 비공개 저장소로 이동했으며(더 가벼운 OSS 런타임), objectstack init은 다시 빌드되고 부팅되는 프로젝트를 스캐폴드합니다.

9.x

9.x 트레인은 10.0 전환 전까지 @objectstack 9.0 – 9.11 기반으로 동작했습니다. 런타임 부트 계약은 8.0과 동일합니다 — createStandaloneStack은 여전히 동일한 아티팩트, 환경, 데이터베이스 설정을 받으므로 8.0 배포는 구성 변경 없이 그대로 업데이트됩니다. 바뀐 것은 작성자(author)가 마주하는 표면입니다:

• 분석 데이터셋이 유일한 작성자 표면이 되었습니다 (9.0, 호환성 깨짐) — 대시보드 위젯, 보고서, 리스트 차트는 이제 의미 기반 dataset (defineDataset(...))에 바인딩하고 차원/측정값을 이름으로 선택합니다. 기존의 인라인 쿼리 필드(위젯의 object/valueField/aggregate, 보고서의 objectName/columns/groupingsDown, 리스트 차트의 xAxisField/yAxisFields)는 제거되었습니다. 마이그레이션: 인라인 쿼리를 defineDataset으로 옮기고 이름으로 참조하세요. ChartTypeSchema도 기본형으로만 렌더링되던 8개의 변형 타입을 삭제했습니다(stacked-bar→bar, spline→line, bubble→scatter, …).
• 더 엄격한 빌드 타임 검증 (9.6–9.7) — os compile은 이제 단독 필드 참조 (record.amount 대신 amount), 알 수 없는 CEL 함수, 잘못된 플로우 값 보간 구문에 대해 각각 did-you-mean 힌트와 함께 실패합니다. 이전에는 "빌드는 되지만 조용히 잘못되던" 스택이 이제 큰 소리로 실패합니다 — 업그레이드 후 os compile을 다시 실행하고 플래그된 항목을 수정하세요.
• 숫자 필드 수식이 혼합 산술을 계산합니다 (9.7) — record.amount / 100과 record.price * 2가 이제 조용히 null을 내놓는 대신 평가됩니다. / 100.0 부동 소수점 리터럴 우회법은 더 이상 필요하지 않습니다.
• 객체 단위 REST 게이팅, 이제 강제됨 (ADR-0049) — 객체의 apiEnabled: false는 해당 객체를 REST 표면에서 제거하고, apiMethods 화이트리스트는 어떤 작업에 도달할 수 있는지를 제한합니다. 이전에는 파싱은 되었지만 강제되지 않았습니다.
• 패키지 문서를 메타데이터로 + book 내비게이션 (9.3–9.6) — src/docs/*.md가 doc 메타데이터로 등록됩니다. book 요소(ADR-0046)는 파생 멤버십 내비게이션 척추를 선언하며, 청중 게이팅과 함께 GET /api/v1/meta/book/:name/tree에서 제공됩니다.
• os package install (9.3) — 카탈로그 id 또는 인라인 에어갭 아티팩트로부터 실행 중인 런타임에 패키지를 설치하며, --email / --password로 인증합니다.
• 승인(Approvals) (9.3) — 수정 요청 반려(maxRevisions, 기본값 3), 잡 기반 SLA 자동 에스컬레이션, 리스트 검색/페이지네이션, 세션 없는 이중 언어 승인/거부 확인 링크.
• 인바운드 웹훅 플로우 트리거 (9.3) — type: 'api' 플로우는 HMAC 검증된 POST /api/v1/automation/hooks/:flowName/:hookId 엔드포인트를 멱등적이고 큐 기반인 수집과 함께 마운트합니다.
• 알림 보존 기본값 켜짐 (9.5) — 알림 기록이 90일에 자동으로 정리됩니다. 기록을 영구 보관하려면 메시징 retentionDays: 0을 설정하세요.
• CLI가 AI 제공자 SDK를 번들합니다 (9.0) — OpenAI 호환 제공자(DeepSeek, DashScope, SiliconFlow, OpenRouter, Cloudflare)가 전역 설치된 CLI에서 별도 설정 없이 동작합니다.

주목할 플로우 작성 동작 변경 하나: create_record 노드의 outputVariable는 이제 (단순 id가 아니라) 생성된 레코드 객체를 담으므로, id를 기대하던 {var} 참조를 {var.id}로 업데이트하세요.

8.0.x

ObjectOS One과 번들 서버는 @objectstack 8.0.1 기반으로 동작했습니다.

• MCP over Streamable HTTP — 모든 배포가 네트워크로 접근 가능한 Model Context Protocol 서버로 동작할 수 있습니다. OS_MCP_SERVER_ENABLED=true로 활성화하면 엔드포인트가 /api/v1/mcp에서 제공되며 fail-closed 인증(익명 요청 거부)이 적용됩니다. 플러그인은 @objectstack/plugin-mcp-server에서 @objectstack/mcp로 이름이 변경되었습니다.
• 셀프 서비스 API 키 — POST /api/v1/keys는 한 번만 표시되는 sys_api_key를 발급합니다. REST 데이터 및 메타데이터 API(/api/v1/data, /api/v1/meta)는 이제 MCP와 동일한 검증기로 API 키를 인증하며, 키 소유자의 권한과 레코드 수준 보안 아래에서 실행됩니다.
• 필드 단위 조건 규칙 — visibleWhen, readonlyWhen, requiredWhen이 폼 UI뿐 아니라 ObjectQL에 의해 서버 측에서 강제됩니다.
• 재사용 가능한 RLS 읽기 필터 — security.getReadFilter(object, context)가 레코드 접근의 읽기 범위를 노출합니다. 분석 데이터셋, 대시보드, 보고서가 여기에 브리지되며 범위를 안전하게 적용할 수 없으면 fail closed 됩니다.
• 독립형 host 스택 — 런타임은 단일 테넌트 createStandaloneStack host를 제공합니다. 7.x의 클라우드 연결·호스트명 라우팅 방식 createObjectOSStack 래퍼는 제거되었습니다. 클라우드 배포는 이제 OS_ARTIFACT_FILE을 게시된 artifact URL로 지정합니다.

5.0 — project → environment 이름 변경 (출시됨)

이전에 Project라고 불리던 런타임 개념이 전반에 걸쳐 Environment로 이름이 변경되었습니다. 영향 범위:

• CLI 플래그: --environment / -e
• HTTP 경로: /api/v1/environments/:environmentId/...
• 헤더: X-Environment-Id
• 환경 변수: OS_ENVIRONMENT_ID (OS_PROJECT_ID는 사용 중단된 별칭으로 유지됨)
• DB 컬럼: environment_id
• JSON 스키마: EnvironmentArtifact

업그레이드

실제 작업 단계는 업그레이드 및 롤백을 참고하세요. 사전 점검:

1. 현재 버전과 대상 버전 사이의 모든 마이너에 대한 CHANGELOG 항목을 읽으세요.
2. os diff <old-artifact> <new-artifact>를 실행하여 호환성을 깨는 스키마 변경을 드러내세요.
3. 대상 버전에 대해 os doctor를 실행하세요.
4. 전체 플릿에 적용하기 전에 카나리 인스턴스 하나를 먼저 띄우세요.
5. 이미지 태그와 아티팩트 버전 모두에 대한 롤백 계획을 마련하세요(둘은 독립적으로 롤백됩니다).

회귀 보고

패치 또는 마이너 버전이 이전에 정상 작동하던 것을 망가뜨린 경우, 업그레이드 전/후 버전과 함께 github.com/objectstack-ai/objectos/issues에 버그를 등록하세요. 회귀는 가장 높은 우선순위의 버그로 처리합니다.