RustBox/docs/UPSTREAM.md

Oxi upstream policy

RustBox is derived from c0h1b4/oxi. UPSTREAM_BASE contains the exact Oxi commit whose backend changes have been consumed by RustBox.

RustBox uses a flat Cargo layout, while Oxi uses a backend/ subtree. The sync tooling therefore treats Oxi as a source upstream and maps its backend paths into RustBox rather than reintroducing the Oxi directory layout.

Path mapping

Examples:

Oxi backend/Cargo.toml          -> RustBox Cargo.toml
Oxi backend/Cargo.lock          -> RustBox Cargo.lock
Oxi backend/rust-toolchain.toml -> RustBox rust-toolchain.toml
Oxi backend/src/...             -> RustBox src/...
Oxi backend/migrations/...      -> RustBox migrations/...
Oxi backend/tests/...           -> RustBox tests/...
Oxi backend/examples/...        -> RustBox examples/...
Oxi backend/docs/...            -> RustBox docs/...

RustBox-owned src/web/ has no automatic mapping from the Oxi frontend.

Configure the upstream

A release archive does not contain .git. Initialize the RustBox repository once:

git init
git add .
git commit -m "RustBox 0.0.1 baseline"
./scripts/setup-upstream.sh

The script adds:

upstream-oxi -> https://github.com/c0h1b4/oxi.git

and fetches Oxi history/tags.

Inspect a newer Oxi state

./scripts/oxi-status.sh

or inspect a specific Oxi ref:

./scripts/oxi-status.sh upstream-oxi/main
./scripts/oxi-status.sh <tag-or-commit>

The report separates:

1. Oxi backend/ changes that can be mapped into RustBox;
2. Oxi frontend/ changes that require a manual UI port;
3. other Oxi root-level changes that require manual review;
4. upstream commits since UPSTREAM_BASE.

Advance the consumed Oxi backend state

./scripts/sync-upstream.sh

The operation:

1. requires a clean RustBox Git worktree;
2. fetches upstream-oxi;
3. verifies that the target descends from the recorded UPSTREAM_BASE;
4. creates a sync/oxi-* review branch;
5. generates the Oxi backend delta from UPSTREAM_BASE to the target;
6. rewrites only patch metadata so backend/<path> becomes <path>;
7. applies the mapped delta with Git three-way merge support;
8. does not import Oxi frontend sources;
9. records the target as a pending sync inside Git metadata;
10. deliberately leaves UPSTREAM_BASE unchanged until the maintainer finishes review.

Conflicts are expected when Oxi and RustBox changed the same functionality. Resolve them in the flat RustBox paths, keeping RustBox-specific behavior where required.

After resolving backend conflicts and porting any relevant UI behavior, finish the sync:

./scripts/finish-upstream.sh

If Oxi changed its frontend or root-level files, the finish step refuses to advance the baseline until you explicitly acknowledge those reviews:

./scripts/finish-upstream.sh --ui-reviewed --root-reviewed

The finish step runs the RustBox release build gate and only then stages the new UPSTREAM_BASE. Review git status and commit the sync. --skip-build exists for exceptional local workflows, but CI should still run the full gate before merge.

If the sync is rejected, discard the review branch; the main branch and its UPSTREAM_BASE remain unchanged.

Port one Oxi feature

For a useful Oxi commit that should be brought in before a full baseline update:

./scripts/oxi-port-commit.sh <oxi-commit>

This creates port/oxi-<sha> and maps only the backend portion of that single commit. It intentionally does not change UPSTREAM_BASE, because RustBox has not consumed the complete Oxi history up to that revision.

When a later full sync includes a previously ported feature, Git may report that some hunks are already present; review those conflicts instead of duplicating the code.

UI policy

Oxi frontend source is never copied into RustBox. For a new Oxi feature that includes frontend work:

• consume or port the backend/API changes;
• inspect the corresponding Oxi frontend diff to understand behavior;
• implement that behavior in RustBox src/web/;
• keep the same-origin RustBox API/UI model;
• do not add .ts or .tsx sources.

RustBox-owned boundaries

These areas require explicit review and should not be replaced blindly by upstream changes:

• src/web/;
• src/ui.rs;
• RustBox UI routing and same-origin behavior;
• RustBox ManageSieve integration;
• dev.sh;
• native packaging/release scripts;
• RustBox branding and documentation.

The goal is to keep following Oxi protocol/backend improvements without restoring its split frontend/backend repository structure.