104 lines
4.4 KiB
Markdown
104 lines
4.4 KiB
Markdown
# nexo Docs
|
|
|
|
This directory holds product notes, migration decisions, and operational
|
|
documentation that apply to more than one module.
|
|
|
|
Module-specific instructions stay with the module that owns them.
|
|
|
|
## Runtime Baseline Index
|
|
|
|
- Workspace runtime and upstream policy: `../README.md`
|
|
- Core compose runtime, deploy loop, smoke checks, remote parity, and secret boundary:
|
|
`../services/core/compose/README.md`
|
|
- Core upstream snapshot baseline: `../services/core/UPSTREAM.md`
|
|
- 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.
|