Skip to content

User documentation

Jump to bottom
Jeffrey Lau edited this page Jun 21, 2023 · 7 revisions

Main concepts

Registers based on RegistryKit use approaches in line with registration procedures outlined in ISO 19135-1. (RegistryKit is being updated to support the latest draft of that standard and is currently about 40% of the way there.)

The list of available actions one may take in register GUI depends on whether the current user is a stakeholder, and what that stakeholder’s role is according to registry metadata. The roles correspond to ISO 19135-1 and include: submitter, register manager, control body, and register owner.

Any changes to the register are made by submitting stakeholder creating a proposal (formerly change request or CR) and having it accepted after a review: first by the register manager, then by the control body, with the possibility of appeal to register owner in case of rejection by the above.

A proposal can include new items (not yet existing in the register), as well as clarifications or amendments to already existing items. A newly created item becomes “valid” when the relevant proposal is accepted. A valid item can be clarified in subsequent proposals any number of times, and finally amended (either simply retired or superseded with another item). Once amended, a register item is no longer considered “valid” (nor “current”) and cannot be further clarified.

Standard compatibility notes:

  • As of now, registers based on RegistryKit are all append-only; removal of items is possible but RegistryKit does not facilitate that in its GUI.
  • Registers based on RegistryKit can still support subregisters, but after being seen as a bit contrived, it is no longer a thing in the latest ISO 19135 (relevant functionality will be removed and any registers relying on RegistryKit will be migrated to subregister-free structures).

GUI

Main working area

RegistryKit features a tabbed GUI, where the following items are always opened in individual tabs:

  • A specific register item: either as of its currently published version in the register, or as proposed in active proposal
  • A proposal, containing any number of register items
  • Register metadata (version, stakeholders)

The “home” (or “new”) tab, always available, contains a shortcut for creating a proposal.

Sidebars

Sidebars can be configured to appear either on the left or the right. There are multiple sidebars, which can be switched between, through icons next to the edge of the window. The main sidebars are 1) Browse, showing items by item class or subregister (if applicable), 2) Search, and 3) Proposals. Double clicking a register item or a proposal shown in any sidebar will open that item in a new tab (or focus that item’s tab if already open).

Active proposal

Activating a proposal is required to make changes, and can be useful when reviewing changes.

A proposal can be made “active” by clicking the “Work on this proposal” or “Activate proposal” button in the main toolbar in the Proposal tab. There can be only one proposal active at a given time.

The effects of active proposal are listed as follows:

  1. All register item tabs and all sidebars will include data as of active proposal. I.e.:

    • if there are any new items, they will also appear in searches and browsers;
    • any clarified or amended items will be shown as such.

  2. A tab displaying an already-existing register item will allow to clarify, retire, supersede that item (subject to status), or to use that item as a template to propose a new item.

  3. Browser sidebar will show an action to propose a new item if you click the “more” button (triple dot) near the register item class label.

Active proposal is indicated by a red bar on top of the application window. Clicking that bar navigates to the tab displaying the active proposal, where it can be deactivated.

Proposal process overview

Submitter

  • From the Home tab, hover over the Propose item, input some short label and click the button right next to the text field. Enter any label that is useful in finding this proposal draft; you will specify a full justification later.

    This should create a new proposal draft and open that proposal in a new tab.

    A commit is created at this point.

  • Activate the newly created proposal draft by clicking the “Work on this proposal” or “Activate proposal” button on the main toolbar.

    A red bar should appear at the top of the window. Clicking that bar will take you back to this proposal’s tab.

  • In the “Browse” sidebar, under the “More” (triple dot) menu near register item class title, click “Propose new”.

    A tab with a newly proposed (blank) item should open. The item should show “addition proposed” status.

    A commit is created at this point.

  • Click the “Edit” button to edit the data of the item being proposed and “Save” if you’re satisfied with your changes.

    Edited data will become part of draft proposal item. Register itself is unaffected.

    A commit is created when you click “Save”.

  • Back in the draft proposal tab, enter a proper justification for the changes you have in mind and submit the proposal.

    Justification is saved locally until you submit the proposal.

    A commit is created when you submit.

Register manager

  • Find and double-click a submitted proposal in the Proposals sidebar.

    A tab with that proposal should open.

  • Approve or reject proposal with a note.

Control body

  • Find and double-click a proposal pending control body review in the Proposals sidebar.

    A tab with that proposal should open.

  • Approve or reject proposal with a note.

    Approved (accepted) proposal will make items in the proposal take effect in the published register version, once all changes have been synchronized.

Clone this wiki locally