Workflows

Purpose: Creation and updating of workflows

Audience: Everyone

Status: Implemented

Rationale

We need workflows when:

  • to not forget important points to be done

  • for collaboration (more than one person is involved in some activity, e.g. approvals are needed)

  • to document how we work that onboarding works better

  • when you need a defined process for systematically collecting, reviewing, and prioritizing multiple related items, rather than handling each one ad-hoc.

    Example: Create a workflow for test case management instead of having developers create test cases individually for every bug they find.

  • for continuous optimizations of how we work

  • we plan to automate a workflow

Workflow Steps

Step 1. Suggest a new Workflow

Who: Person who sees suboptimal workflow being used When: Some informal or suboptimal workflow already exist Actions:

  • create issue that suggests adding or improving a workflow
  • use the enhancement template for issue description
  • in the issue, describe:
    • Use Case: Which problem should be solved / why we need this workflow
    • Description: Which improvement is essential to solve this problem

Step 2. Document Workflow

Who: Person assigned to the issue When: During an iteration Actions:

  • create MR
    • describing the workflow based on doc/workflows/TEMPLATE.md with Draft state
    • add it in the README.md of this folder
    • add line(s) to changelog in Documentation -> Workflows
    • and nothing else in the MR (implementation of the workflow happens in the next step)
  • describe it closely to how we currently do it
  • keep it short and minimal, focus on the main improvement (documentation just as-is is fine, too)
  • If you discover new extensions or improvements, create new issues for each of them
  • create a follow-up issue for Step 4 (workflow implementation):
    • use the enhancement template
    • in Implementation steps, list the tasks needed to implement the workflow (templates, labels, documentation changes, etc.)

Step 3. Approve Workflow

Who: Product and Project Managers When: Review is requested Actions:

  • check if the workflow and follow-up issue is fine and approve MR

Note: Merging will be done via the normal MR workflow.

Step 4. Implement Workflow

Who: Person assigned to the issue When: After Workflow documentation is being merged Actions:

  • In a new MR, change the description of the workflow's State from "Draft" to "Implemented"
  • possibly other fine-tuning or clarifications of the workflow
  • create and update issue and/or MR templates as needed
  • create and change label definitions as needed for the workflow
  • in the next iteration meeting we communicate the changes that the workflow implies for everyone

Step 5. Review Workflow

Who: Project Managers When: After Workflow is being merged Actions:

  • check the workflow by executing it
  • check if all labels etc. were created correctly as documented

Examples

Example 1: Self-Referential (Workflows Workflow)

The process which created this workflow is an example:

Example 2: Issue Creation Workflow

A workflow for creating issues with proper templates and labels:

Tips for Creating Your Own Workflow

When creating a new workflow:

  • Start by identifying a pain point or inefficiency in your current process
  • Use the enhancement template to describe the problem and essential improvement
  • Keep the initial documentation simple - describe how things currently work, plus minimal improvements
  • Save additional enhancements for follow-up issues
  • Involve relevant stakeholders early for feedback

Extensions

  • further fine-tuning or clarifications of the workflow is also possible in meeting MRs or other MRs

Notes