Skip to content

issue-format.instructions.md

Latest commit

 

History

History
84 lines (59 loc) · 2.94 KB

issue-format.instructions.md

File metadata and controls

84 lines (59 loc) · 2.94 KB
applyTo **/github-issues/**

Guidelines for Creating Effective GitHub Issues

Issue Format

When creating GitHub issues, use the following structure to ensure clarity and ease of verification:

For Bug Reports

  1. Title: Concise description of the issue (5-10 words)

  2. Problem Statement:

    • 1-2 sentences describing the issue
    • Focus on user impact
    • Use clear, non-technical language when possible

  3. Steps to Verify Fix:

    • Numbered list (5-7 steps maximum)
    • Start each step with an action verb
    • Include expected observations
    • Cover both success paths and cancellation/back button scenarios

For Feature Requests

  1. Title: Clear description of the requested feature

  2. Need Statement:

    • 1-2 sentences describing the user need
    • Explain why this feature would be valuable

  3. Acceptance Criteria:

    • Bulleted list of verifiable behaviors
    • Include how a user would confirm the feature works as expected

Examples

Bug Report Example

# Terminal opens prematurely with PET Resolve Environment command

**Problem:** When using "Resolve Environment..." from the Python Environment Tool menu,
the terminal opens before entering a path, creating a confusing workflow.

**Steps to verify fix:**
1. Run "Python Environments: Run Python Environment Tool in Terminal" from Command Palette
2. Select "Resolve Environment..."
3. Verify no terminal opens yet
4. Enter a Python path
5. Verify terminal only appears after path entry
6. Try canceling at the input step - confirm no terminal appears

Feature Request Example

# Add back button support to multi-step UI flows

**Problem:** The UI flows for environment creation and Python project setup lack back button
functionality, forcing users to cancel and restart when they need to change a previous selection.

**Steps to verify implementation:**
1. Test back button in PET workflow: Run "Python Environments: Run Python Environment Tool in Terminal",
   select "Resolve Environment...", press back button, confirm it returns to menu
2. Test back button in VENV creation: Run "Create environment", select VENV, press back button at various steps
3. Test back button in CONDA creation: Create CONDA environment, use back buttons to navigate between steps
4. Test back button in Python project flow: Add Python project, verify back functionality in project type selection

Best Practices

  1. Be concise: Keep descriptions short but informative
  2. Use active voice: "Terminal opens prematurely" rather than "The terminal is opened prematurely"
  3. Include context: Mention relevant commands, UI elements, and workflows
  4. Focus on verification: Make steps actionable and observable
  5. Cover edge cases: Include cancellation paths and error scenarios
  6. Use formatting: Bold headings and numbered lists improve readability

Remember that good issues help both developers fixing problems and testers verifying solutions.