Issue Creation Workflow

Purpose: Guide anyone to create well-formed issues with proper templates and initial labels for efficient triage.

Audience: All team members, contributors, and users who report issues or request features.

Status: Draft

Rationale

For properly created issues we need to ensure that:

  • Triage tooling can process issues correctly (requires templates)
  • Essential information is captured upfront
  • Triagers can quickly evaluate and categorize issues
  • No premature labeling decisions are made (scope, priority, status are added later)

Well-formed issues reduce back-and-forth communication and speed up the path from report to resolution.

Quick Reference

Required for Every New Issue:

  • ✅ Use a GitLab issue template
  • ✅ Add triage-needed label
  • ✅ Add type:: label if obvious (bug/enhancement/refactor)

Do NOT Add:

  • ❌ Scope labels (added during triage)
  • ❌ Priority labels (added by PM during sprint planning)
  • ❌ Status labels (added during triage/refinement)
  • ❌ Time estimation (added during triage or refinement)
  • ❌ Assignees (set during sprint planning)

Workflow Steps

1. Determine When to Create an Issue

Who: Contributor

When: Before creating the issue

Actions:

  • Bug discovered: When you encounter unexpected behavior or defects
  • Feature/enhancement idea: When you want to specify a new feature or enhancement that was previously agreed upon
  • Meeting discussion: When a new issue is mentioned in a meeting
    • The person who raised the issue during the meeting should create it
    • See Meeting Workflow for more details
  • Refactoring needed: When code restructuring is required
  • Question/clarification: When discussion is needed

Result: Understand when and why to create an issue

2. Determine Issue Type

Who: Issue creator (team member, contributor, user)

When: Before creating the issue

Actions:

  • Bug: Something broken or not working as expected
  • Enhancement: New feature or improvement to existing functionality
  • Refactor: Code restructuring without changing functionality
  • Question: Decision, Workflow, or other clarifications in documentation needed

Result: Know which template to use

2. Create Issue with Template

Who: Issue creator

When: When reporting a bug, requesting a feature, or asking a question

Actions:

  • Go to GitLab Issues
  • Search issues first, if an issue already exists
  • Click "New issue"
  • Select appropriate template (located in .gitlab/issue_templates/):
  • Important: Do NOT skip template - triage tooling requires it
  • Fill out all template sections completely

Result: Issue created with proper template structure

3. Add Required Labels

Who: Issue creator

When: During issue creation

Actions:

  • Always add: triage-needed label (required)
  • If obvious, add one of the labels scoped with type
  • Do NOT add:
    • Any scope:: labels (backend, frontend, etc.) - triager will add these
    • Any priority:: labels - PM adds during sprint planning
    • Any status:: labels - added during triage or refinement

Result: Issue has minimal required labels for triage

4. Provide Complete Information

Who: Issue creator

When: While filling out the template

Actions:

For Bug Reports, include:

  • Version/branch where bug occurs (SHA-1 or branch name)
  • Expected vs. actual behavior
  • Steps to reproduce the issue
  • Environment details:
    • Operating system
    • Rust version (for backend issues)
    • Node.js/npm version (for frontend issues)
    • Browser (for UI issues)
    • Browser version (if relevant)
    • Database version (if relevant)

For Feature Requests, include:

  • Use case: what problem does this solve?
  • Description of desired functionality
  • Acceptance criteria (what defines "done")

Result: Issue contains all information needed for triage

5. Submit Issue

Who: Issue creator

When: After completing template and adding labels

Actions:

  • Review issue for completeness
  • Verify triage-needed label is set
  • Click "Create issue"
  • Issue automatically enters triage queue

Result: Issue is ready for triage process

Special Cases

Urgent/Critical Issues

If you discover a critical bug affecting production or blocking work:

  1. Still create the issue with template and triage-needed label
  2. Add type::bug label
  3. Mention urgency in the issue description
  4. Notify PM team or triager directly (via GitLab/Nextcloud)
  5. Do NOT add priority labels yourself - PM will handle this

Duplicate Issues

If you discover your issue already exists:

  1. Add a comment on the existing issue with any new information
  2. Close your new issue
  3. Reference the original issue number when closing

Issues Spanning Multiple Components

If unsure which component (backend/frontend/etc.) is affected:

  1. Create the issue anyway with triage-needed
  2. Describe what you observe
  3. Let the triager determine the affected components

Examples

Example 1: Bug Report

Step 1: User discovers map editor crashes when adding certain plants
Step 2: User selects bug template, fills out:
        - Title: "Map editor crashes when adding Tomato plant"
        - Expected: Plant should be added to map
        - Actual: Browser tab crashes
        - Steps to reproduce: 1) Open map, 2) Click "Add plant", 3) Select "Tomato", 4) Click on map
        - Environment: Chrome 120, macOS 14, main branch SHA abc123
Step 3: User adds labels: triage-needed, type::bug
Step 4: User submits issue
Result: Issue #1234 created and enters triage queue

Example 2: Feature Request

Step 1: Product manager wants dark mode for the application
Step 2: Team member selects enhancement template, fills out:
        - Title: "Add dark mode toggle to application settings"
        - Use case: Reduce eye strain for users working at night
        - Audience: All users
        - Description: Toggle switch in settings to enable dark theme
        - Acceptance criteria: Dark theme applied to all pages when enabled
Step 3: Team member adds labels: triage-needed, type::enhancement
Step 4: Team member submits issue
Result: Issue #1235 created and enters triage queue

Example 3: Unclear Scope

Step 1: User notices slow performance when loading large maps
Step 2: User selects bug template (performance issue), fills out:
        - Title: "Map loading takes 30+ seconds for large gardens"
        - Expected: Map loads within 5 seconds
        - Actual: Takes 30-45 seconds
        - Steps: Open any map with 500+ plants
        - Note: "Not sure if this is frontend rendering or backend query issue"
Step 3: User adds labels: triage-needed, type::bug
Step 4: User submits issue
Result: Issue created, triager will investigate and add appropriate scope labels
  • Creating an Issue - Additional guidelines
  • Reporting a Bug - Bug-specific requirements
  • GitLab Issue Templates: .gitlab/issue_templates/
  • Triage Workflow triage.md - What happens after issue creation
  • Issue Refinement Workflow issue_refinement.md - What happens if issue needs more detail

Troubleshooting

Common Issues

Problem: Not sure which template to use Solution: When in doubt, use question.md template, add triage-needed label and comment on created issue that you were not sure which template to use - triager will correct the type

Problem: Don't know what labels to add Solution: At minimum, just add triage-needed - triager will add all other necessary labels

Problem: Issue is complex and affects multiple areas Solution: Create the issue anyway with triage-needed and describe what you observe - triager will determine appropriate labels and may split into multiple issues if needed

Problem: Not sure if this is a bug or expected behavior Solution: Create issue with triage-needed and describe the behavior - triager or PM can determine if it's a bug or wanted behavior

Open Points

  • doc/contrib/README.md probably needs refactoring as it has multiple workflows inside
  • The links in Related Resources need to be activated in follow up as all workflows need to be merged first

Notes