nexo/docs

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
• iOS notification smoke prerequisites and runbook: ios-notification-test-guide.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.