EukMap Workflow

This document describes the workflow implemented by the EukMap platform The workflow is used to curate taxa (nodes in a taxonomic tree): creating new taxa, renaming, moving, replacing and deleting existing taxa, as well as updating a taxon. Changes are prepared in a copy of the taxonomy (draft) by contributors which are then proposed for review (proposal).

Workflow

figures/eukmap-multi_user_workflow.svg

Any changes proposed to any taxon requires to first create draft. Once a draft has been created, the user who created the draft (initiator) or users invited by the initiator may propose changes. All changes are recorded by the platform to document who proposed the change and when it was proposed. This documentation also includes a short systematic description of the change that is use to provide an overview of changes included in the draft and to document the differences between two versions of the taxonomy.

When done, the initiator submits the draft for review at which point the draft becomes a proposal. The proposal is automatically assigned to a reviewer responsible for the taxon / group of taxa or if no reviewer is assigned to the specific group, to the reviewer assigned to the nearest parent taxon. Once proposed, a draft/proposal can no longer be changed but the initiator of the draft / proposal has the option to retract the proposal if additional changes are required.

Review Process

Proposals proposed to change the taxonomy have to reviewed by a reviewer. The reviewer has the option to immediately accept or decline any proposal. If a proposal does not include all required information, contains formal errors, or otherwise cannot be accepted immediately, the proposal may be returned to the user for clarification or to require additional changes (needs work). The reviewer may also invite additional contributors and reviewers to discuss a proposal in case a decision can not be reached immediately. The proposal may be resubmitted once the feedback of the reviewer has been addressed.

GIT actions

Internally, creating a draft will create a distinct branch in the GIT repository. This branch is created from the next version of the taxonomy (candidate) by cloning the GIT repository into a local working copy and is not available in the main GIT repository (origin). The name of the newly created branch is based on the ID of the draft.

Each proposed change made within a draft is a distinct commit on the draft's branch requiring a short descriptive text. The intention of the commit message is to explain the 'technically' change rather than describing the overall intention(s) behind the draft.

When a draft is submitted for review a 'pull request' will be created. This pull request will be kept open throughout the complete review process and its presentation must be updated whenever changes are made to the proposal. Ideally, changes made in response to the reviewer's comments are 'highlighted' to help the reviewer concentrate on the updated proposal instead of having to review to full proposal again.

After a proposal has been accepted or rejected the created branch will be deleted.