Contribution workflow

Overview

Developing content for ASAM standards is focused around the concept of contributing with issues.
The following sections describe this workflow in more detail.

asam contribution workflow StateDiagram.drawio
Figure 1. ASAM contribution workflow
For details on referenced labels, refer to the label overview.

New

What

A new issue that needs to be classified to a type.

Who

Workflow Manager

State Label

Transitions

Issue is a duplicate::→ CLOSED ()
Type assigned::→ CLASSIFIED

To transition to next state

Actions

  • Categorize the issue (i.e. assign the issue type)

    • If the issue has been raised previously or was solved in another issue, assign and close the issue

    • Otherwise, assign the correct type.

Classified

What

An issue that has a type and that needs to be accepted by the group.

Who

Relevant lead (project lead or subgroup lead)

State label

Transitions

Issue is a duplicate::→ CLOSED ()
Issue is rejected::→ CLOSED ()
Issue is accepted::→ ACCEPTED

To transition to next state

Actions

  • Decide whether to address the issue or not

  • If the issue is accepted, it is assigned to a release milestone

  • If rejected, is assigned

  • If duplicate, is assigned

  • If accepted, a release milestone is assigned

Accepted

What

An issue that has been accepted by the project group, which needs to be assigned to a responsible, given a due date and needs a clear specification of requirements to be fulfilled.

Who

Relevant lead (Project Lead or Subgroup Lead)

State Label

Transitions

Prioritized::→ IN PROGRESS

To transition to next state

Actions

  • Assign the issue to a project participant → the solution responsible

  • Define a solution team within the issue description. This may be either of:

    • a project subgroup - assign the respective label of the subgroup to the issue.

    • an unstructured group of project participants, specific to this issue - the names of these participants shall be documented in the issue description.

  • Check if the issue needs to be split into multiple sub-issues or tasks (making it a parent issue)

    • If it needs to be split, each sub-issue enters state ACCEPTED immediately

    • Each sub-issue applies the remaining workflow individually

    • A parent issue may only be closed if all its sub-issues have been closed

  • Set a due date for the solution (should not exceed 4 weeks of development)

  • Clear specification of requirements to be fulfilled by a solution

In Progress

What

An issue that is assigned a responsible, has a due date and clear requirements, which now needs to be implemented in a solution.

Who

Solution responsible (issue assignee)

State Label

Transitions

Solution developed::→ IMPLEMENTED

To transition to next state

Actions

  • Develop a solution together with relevant group (solution team, see Solution development)

  • Document the solution by creating a merge/pull request. Some projects do not yet use the DevOps platforms of ASAM. In this case the solution location is to be agreed on by the project on start.

  • Coordinate, monitor and discuss developments within solution team

  • On solution completion, set a due date for review (should not exceed 2 weeks)

  • Inform project lead and any relevant subgroups of issue review

Implemented::

What

An issue that has a solution in an associated merge request or document, which is ready to be reviewed by the group.

Who

Workflow Manager

State Label

Transitions

Solution accepted::→ REVIEWED
Solution rejected::→ IN PROGRESS

To transition to next state

Actions

  • Perform solution review

    • Project group or delegated subgroup reviews solution and documents their feedback:

      • General feedback: as comment on Merge/Pull Request

      • Specific feedback: as review in changes tab

      • If the solution is documented otherwise, the use of comments in the document is recommended

    • Identified minor corrections are implemented directly in collaboration between reviewers and solution responsible

  • Discuss review results in project group meeting

  • Accept or reject solution and document decision in issue

    • Identified major corrections lead to rejection of solution

    • If accepted, appoint and assign solution to an Integrator (responsible for integrating the solution)

Reviewed

What

An issue that has a been accepted by the group, has an assigned integrator, which is ready to be integrated into the standard or project.

Who

Integrator

State Label

Transitions

Solution implemented::→ INTEGRATED
Major questions::→ IMPLEMENTED

To transition to next state

Actions

  • Refine content and apply ASAM Editorial Guide

  • Document any questions in the issue

  • Clarify minor questions with solution responsible

  • If any major questions arise, change state back to Implemented

  • When integrated (and if applicable), remove the "Draft:" flag from the Merge Request

  • Assign to the solution responsible of the ticket

Integrated

What

An issue that has been integrated, is assigned to the solution responsible, which is ready to be checked and all open comments are resolved.

Who

Solution responsible

State Label

Transitions

Integration OK::→ READYFORMERGE (relevant for merging of branches in docs-as-code)
Integration OK::→ CLOSED () (for projects not using docs-as-code)
Integration NOK::→ REVIEWED

To transition to next state

Actions

  • Review the integration

    • Is the original content still correctly represented?

    • Are all discussions resolved?

  • Add feedback as comments

  • Add verdict as comment in issue

    • If accepted, assign issue to the Workflow Manager

    • If accepted (and if applicable), approve the merge request

Ready for Merge

What

An issue that has been integrated and is assigned to the workflow manager, which is ready to be merged.

Who

Workflow Manager

State Label

Transitions

Merged::→ CLOSED ()
Merge Conflict::→ INTEGRATED

To transition to next state

Actions

Note that this is only applicable to projects with a docs-as-code workflow

  • Merge the assigned Merge/Pull Request

    • If any major merge conflicts arise, these are to be documented and the ticket is reassigned to the Solution Responsible, and change back to the previous state

    • If the merge completes successfully, close the Merge/Pull Request and the associated issue(s)