diff --git a/agent-roadmap/ROADMAP.md b/agent-roadmap/ROADMAP.md index 0d473b73..3a763618 100644 --- a/agent-roadmap/ROADMAP.md +++ b/agent-roadmap/ROADMAP.md @@ -19,9 +19,9 @@ nexo-owned 제품 표면은 Flutter SDK, compose, 운영 계약, 앱별 integrat - [검토중] 제품 기반 정리 - 경로: `agent-roadmap/phase/product-foundation/PHASE.md` - 요약: nexo의 제품 경계, 모노레포 구조, upstream-followable 런타임 기준선을 고정했고 Phase 완료 확인을 기다린다. -- [진행중] 업스트림 런타임 운영화 +- [검토중] 업스트림 런타임 운영화 - 경로: `agent-roadmap/phase/upstream-runtime/PHASE.md` - - 요약: Mattermost server/webapp/push-proxy 업데이트를 계속 따라가기 위한 기준, CI/CD, 장애 대응 루프를 만든다. + - 요약: Mattermost server/webapp/push-proxy 업데이트를 계속 따라가기 위한 기준, CI/CD, 장애 대응 루프를 정리했고 Phase 완료 확인을 기다린다. - [계획] 메시징 런타임 표준화 - 경로: `agent-roadmap/phase/messaging-runtime/PHASE.md` - 요약: nexo-owned Flutter SDK와 upstream runtime이 공유할 메시징/알림 계약, 테스트, 앱별 사용 채널 모델을 정리한다. diff --git a/agent-roadmap/phase/upstream-runtime/milestones/upstream-following.md b/agent-roadmap/archive/phase/upstream-runtime/milestones/upstream-following.md similarity index 72% rename from agent-roadmap/phase/upstream-runtime/milestones/upstream-following.md rename to agent-roadmap/archive/phase/upstream-runtime/milestones/upstream-following.md index 3fb268a4..5d22d37f 100644 --- a/agent-roadmap/phase/upstream-runtime/milestones/upstream-following.md +++ b/agent-roadmap/archive/phase/upstream-runtime/milestones/upstream-following.md @@ -12,7 +12,7 @@ Mattermost server, webapp, push-proxy를 nexo runtime으로 계승하면서도 u ## 상태 -[진행중] +[완료] ## 승격 조건 @@ -44,28 +44,32 @@ Mattermost server, webapp, push-proxy를 nexo runtime으로 계승하면서도 u server/webapp/push-proxy가 어떤 upstream 버전을 기준으로 움직이는지 추적 가능하게 만든다. -- [ ] [source-baseline] server와 webapp의 upstream tag/commit, 적용 patch, nexo-local 변경 범위를 기록하는 기준을 정리한다. -- [ ] [snapshot-script] 외부 `mattermost/` staging clone을 git update하고 선택한 snapshot을 `apps/mattermost`, `services/core`, `services/push-proxy`로 복사하는 workspace script 계약을 정리한다. 검증: script가 staging pull 결과를 자동 merge하지 않고, repo별 commit SHA 기록, snapshot diff 확인, smoke 검증 단계를 분리한다. -- [ ] [push-proxy-baseline] push-proxy를 image-only로 추적할지 source mirror/fork를 둘지 판단 기준과 현재 선택을 문서화한다. -- [ ] [release-watch] Mattermost monthly/ESR release, security patch, push-proxy update를 확인하는 주기와 담당 문서를 정리한다. +- [x] [source-baseline] server와 webapp의 upstream tag/commit, 적용 patch, nexo-local 변경 범위를 기록하는 기준을 정리한다. +- [x] [snapshot-script] 외부 `mattermost/` staging clone을 git update하고 선택한 snapshot을 `apps/mattermost`, `services/core`, `services/push-proxy`로 복사하는 workspace script 계약을 정리한다. 검증: script가 staging pull 결과를 자동 merge하지 않고, repo별 commit SHA 기록, snapshot diff 확인, smoke 검증 단계를 분리한다. +- [x] [push-proxy-baseline] push-proxy를 image-only로 추적할지 source mirror/fork를 둘지 판단 기준과 현재 선택을 문서화한다. +- [x] [release-watch] Mattermost monthly/ESR release, security patch, push-proxy update를 확인하는 주기와 담당 문서를 정리한다. ### Epic: [patch-policy] Patch boundary nexo 변경이 upstream merge를 어렵게 만들지 않도록 허용 경계를 만든다. -- [ ] [thin-branding] webapp은 기본 메시지 앱/reference front로 유지하고, branding과 기능 숨김은 얇은 patch로 제한하는 기준을 정리한다. -- [ ] [no-deep-rename] server/webapp/push-proxy upstream-owned 코드의 대량 rename과 deep fork를 금지하고 예외 조건을 문서화한다. -- [ ] [feature-triage] upstream 새 기능을 keep/hide/defer/remove 후보로 분류하는 기준을 정리한다. +- [x] [thin-branding] webapp은 기본 메시지 앱/reference front로 유지하고, branding과 기능 숨김은 얇은 patch로 제한하는 기준을 정리한다. +- [x] [no-deep-rename] server/webapp/push-proxy upstream-owned 코드의 대량 rename과 deep fork를 금지하고 예외 조건을 문서화한다. +- [x] [feature-triage] upstream 새 기능을 keep/hide/defer/remove 후보로 분류하는 기준을 정리한다. ## 완료 리뷰 -- 상태: 없음 -- 요청일: 없음 -- 완료 근거: 없음 +- 상태: 승인됨 +- 요청일: 2026-05-30 +- 완료 근거: + - `docs/README.md`에 baseline 기록, snapshot script 계약, push-proxy 추적 선택, release watch, patch policy를 정리했다. + - `services/core/UPSTREAM.md`, `services/push-proxy/UPSTREAM.md`, `apps/mattermost/UPSTREAM.md`에 모듈별 patch boundary와 update gate를 보강했다. + - `git diff --check`, task/status `rg`, 활성 경로 확인을 통과했고, workspace lock 관련 항목은 없었다. + - 현재 마일스톤 기능 Task 7개는 문서화 범위 안에서 충족되었고, 실제 snapshot 자동화 스크립트 구현은 이번 마일스톤의 계약 정리 범위를 넘는 별도 큰 작업으로 분리 가능하다. - 리뷰 필요: - - [ ] 사용자가 완료 결과를 확인했다 - - [ ] archive 이동을 승인했다 -- 리뷰 코멘트: 없음 + - [x] 사용자가 완료 결과를 확인했다 + - [x] archive 이동을 승인했다 +- 리뷰 코멘트: 2026-05-30 사용자 요청에 따라 `[완료]` 전환 후 archive 이동했다. ## 범위 제외 @@ -81,5 +85,5 @@ nexo 변경이 upstream merge를 어렵게 만들지 않도록 허용 경계를 - 선행 작업: 정체성 기준선 - 후속 작업: 메시징 계약 표준화 - 완료된 관련 작업: CI/CD와 운영 업데이트 루프는 2026-05-30 archive 완료 -- 다음 작업 지점: `[source-baseline]`에서 server/webapp upstream tag/commit, 적용 patch, nexo-local 변경 범위 기록 기준을 먼저 정리한다. 이후 `[snapshot-script]`로 staging clone update와 snapshot copy 계약을 이어간다. +- 다음 작업 지점: `agent-roadmap/phase/messaging-runtime/milestones/messaging-contract.md` - 확인 필요: 없음 diff --git a/agent-roadmap/current.md b/agent-roadmap/current.md index 92083ab3..40ba1b73 100644 --- a/agent-roadmap/current.md +++ b/agent-roadmap/current.md @@ -2,14 +2,14 @@ ## 활성 Phase -- [진행중] 업스트림 런타임 운영화 - - 경로: `agent-roadmap/phase/upstream-runtime/PHASE.md` +- [계획] 메시징 런타임 표준화 + - 경로: `agent-roadmap/phase/messaging-runtime/PHASE.md` ## 활성 Milestone -- [진행중] 업스트림 팔로잉 기준선 - - Phase: `agent-roadmap/phase/upstream-runtime/PHASE.md` - - 경로: `agent-roadmap/phase/upstream-runtime/milestones/upstream-following.md` +- [계획] 메시징 계약 표준화 + - Phase: `agent-roadmap/phase/messaging-runtime/PHASE.md` + - 경로: `agent-roadmap/phase/messaging-runtime/milestones/messaging-contract.md` ## 선택 규칙 diff --git a/agent-roadmap/phase/upstream-runtime/PHASE.md b/agent-roadmap/phase/upstream-runtime/PHASE.md index 6dee62f7..c7230c30 100644 --- a/agent-roadmap/phase/upstream-runtime/PHASE.md +++ b/agent-roadmap/phase/upstream-runtime/PHASE.md @@ -2,7 +2,7 @@ ## 상태 -[진행중] +[검토중] ## 목표 @@ -18,9 +18,9 @@ Mattermost server, webapp, push-proxy를 nexo의 upstream-followable 메시징 - [완료] CI/CD와 운영 업데이트 루프 - 경로: `agent-roadmap/archive/phase/upstream-runtime/milestones/cicd-operations.md` - 요약: upstream update, compose 배포, 검증 실패 이슈화를 반복 가능한 파이프라인으로 만든다. -- [진행중] 업스트림 팔로잉 기준선 - - 경로: `agent-roadmap/phase/upstream-runtime/milestones/upstream-following.md` - - 요약: server/webapp/push-proxy의 upstream baseline, patch 경계, update 판단 기준을 정한다. +- [완료] 업스트림 팔로잉 기준선 + - 경로: `agent-roadmap/archive/phase/upstream-runtime/milestones/upstream-following.md` + - 요약: server/webapp/push-proxy의 upstream baseline, snapshot script 계약, patch 경계, update 판단 기준을 정리하고 사용자 승인에 따라 archive했다. ## Phase 경계 diff --git a/apps/mattermost/UPSTREAM.md b/apps/mattermost/UPSTREAM.md index bb05a034..8ac19e86 100644 --- a/apps/mattermost/UPSTREAM.md +++ b/apps/mattermost/UPSTREAM.md @@ -9,4 +9,22 @@ - Snapshot source: `/config/workspace/mattermost/mattermost-mobile/` - Snapshot target: `/config/workspace/nexo/apps/mattermost/` -Keep nexo-specific changes outside this snapshot where possible. +## Patch Boundary + +Keep nexo-specific changes outside this snapshot where possible. This app is a +Mattermost mobile reference clone for runtime verification, not the nexo +product app surface. + +Do not add app-specific nexo product UI or business logic here. Prefer docs, +test evidence, wrapper scripts, or small compatibility patches when the clone +is needed for runtime validation. + +## Update Gate + +A Mattermost mobile snapshot update must stay separate from core and +push-proxy updates. Before a merge request, record the selected upstream +commit, review the snapshot diff, and run the relevant app smoke or test lane. + +When app verification depends on local-only credentials or endpoints, record +only sanitized evidence in tracked docs and keep raw environment values outside +git. diff --git a/docs/README.md b/docs/README.md index aa44a082..f9378ee7 100644 --- a/docs/README.md +++ b/docs/README.md @@ -14,3 +14,91 @@ Module-specific instructions stay with the module that owns them. - Mattermost mobile app upstream snapshot baseline: `../apps/mattermost/UPSTREAM.md` - Mattermost push-proxy upstream snapshot baseline: `../services/push-proxy/UPSTREAM.md` - Runtime Image Validation details: `runtime-image-validation.md` + +## Upstream Following Policy + +Mattermost upstream repositories are runtime baselines, not the main nexo +product surface. Keep `apps/mattermost`, `services/core`, and +`services/push-proxy` close to their recorded upstream snapshots, and put +nexo-owned behavior in the Flutter SDK, compose/runtime wrappers, docs, or +small explicit compatibility patches. + +### Baseline Records + +Each upstream snapshot owner keeps an `UPSTREAM.md` file with: + +- source repository URL; +- tracked branch and release tag when applicable; +- exact upstream commit SHA; +- snapshot date; +- snapshot source and target path; +- accepted nexo-local patch boundary; +- update gate and smoke evidence expected before a merge request. + +When a baseline changes, update the matching `UPSTREAM.md` in the same change +as the snapshot. Do not mix app, core, and push-proxy snapshot updates in one +merge request. + +### Snapshot Script Contract + +A workspace snapshot helper may automate only the mechanical staging and copy +steps. Its contract is: + +- update the external `mattermost/` staging clone for one selected upstream + repository at a time; +- read the tracked branch from the module's `UPSTREAM.md` or project rules; +- copy the chosen snapshot only to the matching target directory; +- exclude `.git`, dependency caches, build outputs, runtime data, logs, and + ignored secret-bearing files; +- record the selected upstream commit SHA for the operator to apply to the + matching `UPSTREAM.md`; +- print the follow-up diff review and smoke checklist. + +The helper must not commit, push, update multiple upstream repositories in one +run, promote runtime images, or auto-merge staging pull results into this +workspace. Snapshot diff review and smoke verification remain separate gates. + +### Push-Proxy Baseline + +Current choice: keep `services/push-proxy` as a source snapshot mirror of +`mattermost-push-proxy`, and build nexo-owned runtime images from that source +when needed. Runtime image tags and digests are deployment evidence, not the +source baseline. + +Image-only tracking is allowed only after a separate roadmap decision when no +local source build, patch, config packaging, or smoke diagnosis needs the +source snapshot. If that decision changes, update `services/push-proxy/UPSTREAM.md` +and this section together. + +### Release Watch + +Check Mattermost server/webapp monthly releases, active ESR updates, security +notices, Mattermost mobile updates used for verification, and push-proxy +releases before opening a baseline update. Security patches are triaged as soon +as they are noticed; normal monthly or ESR refreshes can wait for an explicit +snapshot lane. + +The public record for a release watch is the relevant `UPSTREAM.md` plus +sanitized runtime evidence in `runtime-image-validation.md` when images or +compose inputs change. Raw credentials, private endpoints, and environment +values stay out of tracked docs. + +### Patch Policy + +Webapp branding and feature visibility changes must stay thin: prefer upstream +configuration, feature flags, small compatibility wrappers, or isolated style +patches. Do not rewrite the webapp into a nexo-owned product surface in this +runtime baseline. + +Do not apply bulk renames, package-wide reformatting, repository reshaping, or +deep fork changes to upstream-owned server, webapp, app, or push-proxy code +without a separate roadmap decision. Exceptions require an explicit rollback +path and a note explaining why an upstream-compatible wrapper is insufficient. + +Classify upstream features during refresh as: + +- `keep`: compatible with nexo runtime and low maintenance cost; +- `hide`: available upstream but disabled or hidden by configuration or a thin + patch; +- `defer`: not adopted until SDK, compose, or app compatibility is ready; +- `remove`: excluded only with a documented compatibility or security reason. diff --git a/services/core/UPSTREAM.md b/services/core/UPSTREAM.md index fb32a88f..3b3d689d 100644 --- a/services/core/UPSTREAM.md +++ b/services/core/UPSTREAM.md @@ -3,10 +3,32 @@ `services/core/` is derived from the Mattermost server repository. - Source: `https://github.com/mattermost/mattermost.git` +- Branch: `master` - Baseline tag: `v11.4.2` - Baseline commit: `bcf511968217cd0f65cbead926e03260bfcd1011` - Snapshot date: `2026-05-30` +- Snapshot source: external `mattermost/mattermost/` staging clone +- Snapshot target: `services/core/` +- Tracked components: Mattermost server and bundled webapp from the same + upstream repository snapshot. -Keep product-specific changes small and easy to compare against this baseline -until the long-term fork and rebranding strategy is settled. +## Patch Boundary +Keep product-specific changes small and easy to compare against this baseline. +Prefer compose files, docs, wrapper scripts, config, and isolated compatibility +patches over changes inside upstream-owned server or webapp code. + +Do not use `services/core` for broad nexo product UI work, package-wide rename, +or deep fork behavior. If an exception is needed, record the upstream feature +classification, changed paths, rollback path, and smoke evidence with the +snapshot update. + +## Update Gate + +A core snapshot update must stay separate from Mattermost mobile app and +push-proxy updates. Before a merge request, record the selected upstream commit, +review the snapshot diff, run the relevant core compose smoke, and classify any +failure as `server`, `webapp`, `push-proxy`, `SDK contract`, or `infra`. + +When runtime images change, keep image tag and digest evidence in +`docs/runtime-image-validation.md`; the source baseline remains this file. diff --git a/services/push-proxy/UPSTREAM.md b/services/push-proxy/UPSTREAM.md index 264db1ff..519ca6e7 100644 --- a/services/push-proxy/UPSTREAM.md +++ b/services/push-proxy/UPSTREAM.md @@ -9,4 +9,31 @@ - Snapshot source: `/config/workspace/mattermost/mattermost-push-proxy/` - Snapshot target: `/config/workspace/nexo/services/push-proxy/` -Keep nexo-specific changes outside this snapshot where possible. +## Current Baseline Choice + +`services/push-proxy` is tracked as a source snapshot mirror, not as image-only +metadata. Nexo runtime images are built from this source snapshot and recorded +separately as deployment evidence. + +Image-only tracking is allowed only after a separate roadmap decision when no +local source build, patch, config packaging, or smoke diagnosis needs the +source snapshot. + +## Patch Boundary + +Keep nexo-specific changes outside this snapshot where possible. Prefer compose +configuration, docs, wrapper scripts, and small explicit compatibility patches. + +Do not absorb push-proxy into `services/core`, rename upstream-owned packages in +bulk, or reshape the repository without a separate fork decision and rollback +path. + +## Update Gate + +A push-proxy snapshot update must stay separate from core and Mattermost mobile +app updates. Before a merge request, record the selected upstream commit, +review the snapshot diff, run the relevant push-proxy or compose smoke, and +classify any failure as `push-proxy`, `server`, `SDK contract`, or `infra`. + +When runtime images change, keep image tag and digest evidence in +`docs/runtime-image-validation.md`; the source baseline remains this file.