Issue Reporting Guidelines

Standards for reporting bugs and requesting features to ensure issues contain complete, actionable information.

Bug Reporting Standards

Essential Information

Every bug report must include:

1. Version/Branch Information

  • Version number or branch name where bug occurs
  • Specific commit SHA-1 if known (use git log to find)
  • Release version for production bugs

2. Behavior Description

  • Expected behavior: What should happen
  • Actual behavior: What actually happens
  • Be specific and objective in describing both

3. Reproduction Steps

  • Step-by-step instructions to reliably reproduce the issue
  • Start from a known state (e.g., "1. Open a fresh browser tab")
  • Number each step clearly
  • Include all necessary actions, no matter how obvious
  • Example: 
    1. Open map editor
2. Click "Add plant" button
3. Select "Tomato" from dropdown
4. Click on map canvas
5. Browser tab crashes

4. Environment Details

Provide relevant environment information:

  • Operating System

    • Name and version (e.g., "macOS 14.1", "Ubuntu 22.04", "Windows 11")

  • For Backend Issues:

    • Rust version (use rustc --version)
    • Cargo version
    • Database version (PostgreSQL + PostGIS)
    • Any relevant environment variables

  • For Frontend Issues:

    • Node.js version (use node --version)
    • npm version (use npm --version)
    • Package manager (npm, yarn, pnpm)

  • For UI/Browser Issues:

    • Browser name and version (e.g., "Chrome 120.0", "Firefox 115")
    • Screen resolution if relevant
    • Device type (desktop, mobile, tablet)
    • Any browser extensions that might interfere

5. Error Messages and Logs

  • Complete error messages (don't paraphrase)
  • Stack traces if available
  • Console errors (browser console or terminal)
  • Relevant log excerpts
  • Use code blocks for formatting

Bug Report Quality

Good Bug Report Characteristics:

  • Developer can reproduce the issue immediately
  • No ambiguity about what's wrong
  • Clear difference between expected and actual behavior
  • All necessary context provided upfront

Common Bug Report Mistakes:

  • Vague descriptions: "It doesn't work"
  • Missing reproduction steps
  • Only describing symptoms, not the behavior
  • Assuming developers know your environment
  • Incomplete error messages

Special Cases

Intermittent Bugs:

  • Note frequency (e.g., "Happens about 1 in 10 times")
  • Include any patterns observed
  • Describe what varies between occurrences

Performance Issues:

  • Quantify the problem (e.g., "Takes 30 seconds, expected 5 seconds")
  • Include data set size or scope
  • Note whether issue gets worse over time
  • Browser/system performance metrics if available

Visual/UI Bugs:

  • Include screenshots or screen recordings
  • Annotate images to highlight the issue
  • Note if issue appears in specific screen sizes
  • Include relevant CSS/styling information

Feature Request Standards

Essential Information

Every feature request must include:

1. Use Case

  • What problem does this solve?

    • Describe the user need or pain point
    • Explain the context where this feature would be used
    • Who is the target audience?

  • Why is this important?

    • Impact on users or workflows
    • Benefits of implementing this feature
    • Consequences of not having this feature

2. Description of Desired Functionality

  • What should the feature do?

    • Clear, specific description of the proposed functionality
    • User-facing behavior and interactions
    • Expected system responses

  • How should it work?

    • User workflow or interaction flow
    • Key features and capabilities
    • Integration with existing functionality

3. Acceptance Criteria

  • What defines "done"?

    • Specific, measurable criteria
    • Test scenarios that must pass
    • Edge cases to handle
    • Performance or quality requirements

  • Use clear, testable statements:

    ✅ Good: "User can filter plants by sun requirements with results updating in <1 second"
❌ Bad: "Filtering should be fast and work well"

Feature Request Quality

Good Feature Request Characteristics:

  • Clear problem statement
  • Concrete, achievable scope
  • Measurable success criteria
  • Considers integration with existing features
  • Realistic and feasible

Common Feature Request Mistakes:

  • No clear problem statement
  • Too vague: "Make it better"
  • No acceptance criteria
  • Unrealistic scope
  • No consideration of edge cases

Describing the Audience

Specify who will use this feature:

  • All users: Everyone using the application
  • Specific user types: Gardeners, administrators, power users
  • Team members: Developers, project managers
  • Stakeholders: Product owners, business users

Optional but Helpful

Examples and Mockups:

  • UI mockups or wireframes
  • Example scenarios or user stories
  • References to similar features in other applications

Technical Considerations:

  • Suggested implementation approach (if you have ideas)
  • Related features or dependencies
  • Performance implications
  • Backward compatibility concerns

Priority and Impact:

  • How urgent is this need?
  • How many users would benefit?
  • What's the workaround if this doesn't exist?

General Reporting Best Practices

Before Creating an Issue

  1. Search for duplicates

    • Check existing open and closed issues
    • Use various search terms
    • Look for similar symptoms or requests

  2. Verify the issue

    • Confirm it's actually a bug or a legitimate need
    • Try to reproduce consistently
    • Check if it's already documented as expected behavior

  3. Gather information

    • Collect all necessary details before creating the issue
    • Take screenshots or recordings
    • Copy full error messages

Writing Style

  • Be clear and concise

    • Use simple, direct language
    • Break information into sections
    • Use lists and formatting for readability

  • Be objective

    • Describe facts, not opinions
    • Avoid emotional language
    • Focus on behavior and impact

  • Be specific

    • Provide exact values and measurements
    • Use concrete examples
    • Avoid vague terms like "sometimes" or "usually"

Follow-Up

  • Respond to questions promptly

    • Triagers or developers may need clarification
    • Provide additional information when requested
    • Test proposed fixes or workarounds

  • Update if situation changes

    • Note if the issue resolves itself
    • Report if symptoms change
    • Add new reproduction steps if discovered

Templates

Always use GitLab issue templates (located in .gitlab/issue_templates/):

  • Templates ensure all necessary information is captured
  • Triage tooling requires proper template usage
  • Structured format aids quick understanding

Choose the appropriate template:

  • bug.md - For bugs and defects
  • enhancement.md - For features and improvements
  • question.md - When unsure or need clarification