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: Implemented

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 (bug/enhancement/refactor/question)
    • Not sure which template? Use question

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, or when unsure if observed behavior is a bug or feature

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:
    • Decisions, workflow, or documentation clarifications needed
    • Unsure if observed behavior is a bug or feature (triage will determine)
    • General uncertainty about which template to use

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)
  • Add type label: Add the appropriate type:: label (bug/enhancement/refactor/question)
  • 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

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: Use the question template with triage-needed label and describe the behavior - triager or PM will determine if it's a bug or feature during triage

Open Points

None - workflow is fully implemented.

Notes