135 lines
4.5 KiB
Markdown
135 lines
4.5 KiB
Markdown
# 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:
|
|
|
|
```text
|
|
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:
|
|
|
|
```bash
|
|
git init
|
|
git add .
|
|
git commit -m "RustBox 0.0.1 baseline"
|
|
./scripts/setup-upstream.sh
|
|
```
|
|
|
|
The script adds:
|
|
|
|
```text
|
|
upstream-oxi -> https://github.com/c0h1b4/oxi.git
|
|
```
|
|
|
|
and fetches Oxi history/tags.
|
|
|
|
## Inspect a newer Oxi state
|
|
|
|
```bash
|
|
./scripts/oxi-status.sh
|
|
```
|
|
|
|
or inspect a specific Oxi ref:
|
|
|
|
```bash
|
|
./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
|
|
|
|
```bash
|
|
./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:
|
|
|
|
```bash
|
|
./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:
|
|
|
|
```bash
|
|
./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:
|
|
|
|
```bash
|
|
./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.
|