Skip to content

Upstream reference discipline

VerifiedOwner Documentation integratorLast verified backend@efa38e04e2db37a444e9f17100323c2ad4b83647 nautilus@2.0.0rc3

ONIX is built on NautilusTrader, pinned at version 2.0.0rc3. A large share of the system's behaviour is therefore not ONIX's behaviour at all. Writing about it as though it were causes two distinct failures: the documentation drifts when upstream changes, and engineers reimplement things that already exist.

This page is the rule that prevents both.

Reference before invention

Before documenting — or building — a concept, check whether upstream already defines it. Instruments, bars, order lifecycle, positions, portfolio accounting and the backtest engine are upstream concepts. So are most of the enumerations that surround them: order types, sides, time-in-force values, and the statuses an order moves through.

If upstream defines it:

  • Link to upstream documentation. Do not restate the definition.
  • Name the pinned version. Upstream behaviour is only well-defined relative to a version, and ONIX pins 2.0.0rc3.
  • Document only the seam. What ONIX passes in, what it reads out, and what it constrains.

If upstream does not define it, you may document it as ONIX behaviour — after checking, and after recording that you checked.

Scoping an extension

Sometimes ONIX must extend upstream. An extension is legitimate when it is deliberate, bounded and labelled. It is a defect when it exists because nobody looked upstream first.

A documented extension must state four things:

  1. What upstream does without the extension.
  2. What ONIX changes or adds, in behavioural terms.
  3. Why — the specific problem that upstream behaviour did not solve.
  4. The support consequence — what a reader can and cannot rely on, and whether the extension is publicly distributed.

Extensions carry the ONIX extension status token. See the NautilusTrader boundary for the current set.

Private modifications

Some ONIX modifications to upstream are private and not publicly distributed. These are documented only as a support boundary: a reader is told that a difference exists, in which area, and what it means for support expectations.

Never publish: patch contents, diffs, build recipes, artifact hashes, reconstruction instructions, or anything else that would let a third party rebuild a private artifact. A support boundary is a statement about expectations, not a distribution channel.

What may never be copied

  • Upstream NautilusTrader documentation. Link to it. Its licence, its accuracy and its maintenance are upstream's responsibility, and a copy in this repository would be a stale fork of all three.
  • Licensed third-party documentation or assets, including charting-library documentation and imagery. Name the library; link to the vendor.
  • Upstream source into documentation pages, beyond the short illustrative fragments that normal technical writing requires.

The practical test

Before writing a paragraph about behaviour, ask:

If upstream changed this next month, would this paragraph become wrong, and would anyone notice?

If the answer is yes to both, the paragraph should be a link. If the answer is yes to the first and no to the second, the paragraph is exactly the kind of sentence that quietly poisons a documentation set, and it should be a link with the version named.

Evidence and source pins for this page

Verified. Current behaviour, confirmed in source at the pinned commit.

Verified on against the following immutable sources:

  • backend@efa38e04:docs/handoff/contract-manifest.json
  • backend@efa38e04:feature-state/rc3-data-plane-frozen-current-production.yaml

Status tokens are defined on the documentation and status model page. Every pin on this site is listed under versions and source pins.