permalinkOntology proposals

Ontology proposals allow you to make changes to an Ontology on a branch, which is based on the main version of that Ontology. This process ensures that all modifications are reviewed and approved before being incorporated into the main Ontology.

Learn more about branching on Foundry.

permalinkDefinitions

• Branch: A branch on the Ontology is a separate version of that Ontology, derived from the main version, designed to enable experimentation and changes without impacting the main branch. This allows users to test and refine adjustments to the Ontology in an isolated environment before merging them back into the main branch.

• Proposal: A proposal is analogous to a Pull Request in a version control system, specifically tailored for Ontology branches. A proposal is automatically created alongside a branch and contains metadata such as reviews, name, and descriptions of the changes being merged into the main branch. Proposals serve as a mechanism for reviewing and approving changes made in a separate branch before they are integrated into the main Ontology.

permalinkProposal workflow

1. Create your branch

You can create a branch by selecting Create Branch to open a dialog where you can choose a title and description for your proposal.

Alternatively, if you already have changes to the Ontology that you would like to include in your proposal, you can select save and toggle Propose your changes from the save dialog.

If you're on the main branch of your Ontology, and you have no changes, you can also create a branch by choosing the branch select component and typing a name for the new branch.

Proposal branches can only be created on the main Ontology configuration. You cannot create a new branch based on another proposal.

While on a branch, a branch navigation top bar located above the workspace interface reflects your current branch.

2. Prepare your proposal for review

At this point, depending on how you created your proposal, you may already have some changes on your branch. While on your branch, you can continue making changes to Ontological resources, including creation and deletion.

Every modified Ontological entity will constitute a separate Task in your proposal and made available for review.

For resources that have migrated to use Ontology roles, viewers can make changes to resources in a proposal. If the resource is on datasource derived permissions, only editors or owners can make changes to them on a proposal.

3. Request a review

After making changes to the branch, you may add reviewers to your proposal. To do so, navigate to your Proposal view, by selecting Open proposal details located in the top bar.

If you exited your branch, you can go to your proposal overview either by navigating to the Proposals tab and selecting your proposal, or by using the branch select component.

From there, assign reviewers from the Reviewers section.

Reviewers will not be notified until the proposal is in the In review stage.

4. Review the proposal

Reviewers may approve or reject individual tasks in the Reviews tab, and may add comments to support their review.

Reviewers must have owner or edit permissions to be able to approve a change.

Users without permissions may still review the task, for example, to convey their opinions on the change, but this will not affect the approved status of the task.

If the creator of the proposal has owner or editor permissions on all the edited resources, they will be able to approve their own changes.

5. Release the proposal

Once your changes have been reviewed and approved, the proposal can be merged into the Ontology.

After a proposal is merged, it will be moved from the In Review section to the Merged section in the sidebar.

At any point of time before you merge the proposal, you can close the proposal by selecting delete from the sidebar.

Proposals can only be merged into the main Ontology configuration.

Proposals cannot be reverted automatically. To undo a proposal, you must undo the different changes within it.

permalinkProposal navigation

• The branch navigation bar: Appears at the top of your workspace when you are editing a branch. From there you may:

• Return to the main branch (1)

• View the proposal details (2)

• Choose a specific branch to navigate to using the branch selector (3)

• Selecting a branch: Choose a branch to edit or view directly from the branch selector section on Ontology Manager's home page.

• The Proposals tab: From the proposals tab, you can choose to view proposals in different status. Definitions of the statuses are below:

  • My proposals: Proposals authored by you.
  • Assigned to me: Proposals where you have been assigned as a reviewer.
  • In review: Proposals that are in progress or approved.
  • Merged proposals: Proposals that have been merged to the Ontology.
  • Closed proposals: Proposals that have been closed out, and were not merged.

  

• The Proposal View: Access the Overview, Reviews, and Changelog tabs for more information about your proposal.

permalinkProposal view

The Proposal Overview centralizes information about your proposal, including the stage it is in, the changes that have been made, the tasks that require review, and the selected reviewers. To access this view for the proposal you are currently editing, select Go to proposal overview located on the top bar. To access the overview page of any proposal, you may do so by navigating to the Proposals tab and selecting the proposal you wish to view.

• Proposal stages: The first stage of a proposal is the Preparing stage. Select Ask for review to move your proposal to the In Review stage. After all tasks have been reviewed and approved, the proposal moves to its final stage, Merge proposal. From this point on, you may merge your changes to the main Ontology using the same option.

• View changes on your branch: Edits are displayed at the bottom of the Overview page. Edits are categorized by Author and by Task, where a Task corresponds to an Ontological resource. You may view the change, navigate to the resource, or discard that change. The history of changes is also accessible through the Changelog tab, where the exact timings of changes are also displayed.

• View and add reviewers: Assign specific colleagues to review your proposal. Reviewers will only get notified once the proposal has moved to the Review stage.

• View tasks that require attention: This section will display all rejected Tasks in the Review stage.

Copy the proposal link to easily share it with peers.

permalinkReviews

The Reviews tab shows all tasks in the proposal. From here, you can perform the following actions:

• Expand the details of each task to view what has been modified
• Leave comments at the level of a task, and collaborate with your peers
• Approve or reject tasks on a task-level, or in bulk for all eligible tasks
• Request additional reviewers

permalinkChangelog

The Changelog tab shows a detailed history of changes on a branch. Tasks can be expanded to reveal edits made by a certain user at a certain point in time. You may also directly navigate to the relevant ontological resource.

permalinkProposal permissions

• Viewing a proposal: A proposal's title and description are discoverable by everyone who has access to the Ontology. Any user with at least viewer access to some resources in the proposal can see the changes related to those resources.

• Creating a proposal: Anyone with viewer access to the Ontology can create a proposal.

• Editing a branch: The creator, and any user with editor or owner permissions on any edited resource in the proposal can edit a branch.

• Editing entities on a branch: Anyone who can edit the branch (see above) can edit an entity on that branch if they have at least viewer access on the entity.

• Accepting or rejecting tasks in a proposal: Anyone can approve or reject changes, or leave comments on a proposal. For the task to be counted as approved, the approver must be either an editor or owner of the underlying resource.

• Releasing a proposal: Once a proposal has been approved, anyone who can edit the branch can release the proposal.

permalinkProposal settings

Ontology proposals are disabled by default. Organization administrators may enable this feature for their organization in Ontology settings in Control Panel.

Ontology proposals will be available to users if:

1. Ontology proposals are enabled for their primary organization.
2. Their primary organization was added to the Ontology using space access requirements in Control Panel.
3. They have access to the Ontology.

Ontology proposals will not be available for guest users of an organization if their primary organization has disabled Ontology proposals. This applies even if the organization they are a guest of has enabled Ontology proposals.

For example:

• User A has Org X as primary organization.
• User B has Org Y as primary organization.
• Org X has enabled Ontology proposals.
• Org Y has not enabled Ontology proposals.
• Space Z has both Org X and Org Y listed in its access requirements in Control Panel.
• User A will see Ontology proposals in the Space Z Ontology, Ontology Z.
• User B will not see Ontology proposals in Ontology Z.
• Even if User B is a guest in Org X, they still will not see Ontology proposals in Ontology Z.