Stomra Guides

EikHub · Guide

EikHub basics

EikHub is where buildings branch, get reviewed and merge, the way software does. This guide explains its core ideas as they work today.

Authoring tools save versions of a building to EikHub; main is the agreed line, an alternative tries something on, and a proposal is reviewed, approved by owners and merged by a person Stomra Femra Varmra ek and assistants edit or propose and save versions A BUILDING ON EIKHUB main merged alternative: wider south window proposal: deeper beam over the kitchen review owners a person merges
The tools edit; EikHub keeps the versions and coordinates. Main is the agreed state of the building. An alternative tries something without touching main. A proposal asks to bring a change into main: it is reviewed, its owners approve, and a person merges it.

The idea

An OpenEik building is stored as a code base: one small text record per element, in folders. That makes it possible to work on a building the way software teams work on code. EikHub is the place where that happens between people and firms.

EikHub coordinates; it never edits the model. Models are changed in the authoring tools: Stomra, Femra, Varmra, the ek command line and the assistants that work through them. On EikHub people look, compare, comment, review, approve, merge and send. A review, a sign-off or a receipt kept on EikHub is offered as a file, and the authoring tool saves it into the building.

Buildings and organisations

A building is one project: its model, drawings and analyses, with all their history. Each building belongs to an organisation, a firm or a client, and has an address on EikHub of the form organisation/building.

Versions and history

A version is a snapshot of every record of the building at one moment, saved by an authoring tool. A version never changes; it is named by a hash of its content, so the same building state always has the same name.

Lines of work: main and alternatives

Main is the building's agreed line of work. An alternative is a line of work to try something on, such as a wider south window or a second stair. Main stays as it is until an alternative is merged into it.

  1. In History, pick the version to start from and choose Start an alternative here. Give it a name.
  2. Work on the alternative in the authoring tool. Its versions build up on its own line.
  3. Compare it with main whenever you like. When it is the one, propose it into main.

Each line of work has its own drawings and analyses, so an alternative can be judged on the drawings and numbers people actually read.

Proposals

A proposal asks to bring a change into a line of work, usually main. It is EikHub's equivalent of a pull request. A proposal comes from an alternative of the building, or from a fork: a copy of the building in another organisation that remembers where it came from, as a supplier or a consultant uses.

A proposal shows:

How a proposal is merged

  1. The proposer opens the proposal and asks reviewers.
  2. Reviewers comment, then approve or ask for changes. A change after a review asks them to look again.
  3. Where the building has owners, every owner whose part the change touches approves it (see Owners by discipline).
  4. An admin of the building merges it on EikHub's confirm page, signed in in the browser. The merge goes record by record and field by field; where both sides changed the same field, the admin chooses which to keep.
  5. EikHub signs a receipt of the merge. Other open proposals against the same line are closed, and can be reopened.

Agents propose, people merge. An app or an assistant can open a proposal for you, but no token merges one: a merge is always a person's act on the confirm page. If your own agent opened it, another admin merges it, unless you are the building's only admin, in which case EikHub asks you to confirm once more.

A proposal is seen only by its parties: the building's admins and the organisation that proposes. That holds on public buildings too, so a supplier never sees another supplier's offer.

Reviews and comments

Owners by discipline

A building can say who owns which part of the model in an owners file, project/owners.json, as OpenEik Part XVI defines it. It names the parties, such as the architect, the structural engineer and the heating and plumbing engineer, and the paths each owns: the structure's folders to the structural engineer, for example. In OpenEik's owners' layout each discipline's records sit in its own folder, so the rules stay short.

People, roles and sharing

RoleCan
readSee the model, history, drawings and analyses; comment and review.
writeAlso save versions, start alternatives, open proposals, plan issues and send drawings.
adminAlso manage people and settings, and merge proposals.
supplierRead, fork and propose from its own fork; never write to the building.

In Stomra, sharing a project by discipline writes the owners file that EikHub enforces; see Sharing by discipline.

The notice board

The Notices tab is a board for things everyone working on the building, people and agents, should know:

The tabs of a building

TabWhat it holds
ModelThe latest version on main in 3D, with its records and comments.
HistoryVersions, lines of work, and comparing two versions.
DrawingsThe register of issued drawings, issues and reviews.
AnalysesAnalyses kept beside the model, such as Femra's structural and Varmra's energy results, each marked when what it was computed from has changed.
ProposalsOpen, merged and closed proposals you are a party to.
NoticesThe notice board: notices, claims and holds.
PeopleMembers, invitations and the organisations it is shared with.
SettingsFor admins: public or private, the rules a proposal must meet before it merges (required approvals and checks), and the owners.