Guidelines: Issues - RoboCupAtHome/RuleBook GitHub Wiki

This document describes the guidelines for posting issues in the repository.

If you have questions about the rules check these guidelines.

Posting

Before posting an issue

Before posting an issue:

  1. Check it is not a question (for questions go here).
  2. Check the issue has not been reported before.
  3. Read all the guidelines in this document.

Quick guide

In a nutshell, the steps to follow are the following:

  1. Only one subject per issue
    • Multiple issues when unrelated
    • Checkboxes when related
  2. The title is short and descriptive
    1. It encapsulates the problem in 3 to 5 words
    2. Avoid unnecessary CAPS
    3. Include the name or acronym of the test
  3. The body of the issue is concise but explicative
    1. The first paragraph summarizes the problem.
    2. Following paragraphs details the problem and provide examples when necessary.
    3. Use images only if necessary.
    4. Be brief.
    5. Mind your spelling.
    6. Mind your grammar.
  4. Your issue has proper references
    • Include related issues when pertinent
    • Link reference to branch/file/line-number when quoting
    • Link reference to commits when necessary
  5. Your issue is properly labeled
    1. Always label your issue accordingly with the test, ability, or rule label.
    2. For issues affecting several tests, label for all tests.
    3. Suggestions and comments must have the idea label.
  6. Your issue has a proper milestone
    • Current year milestones for current rulebook.
    • Years to come milestones for suggestions, roadmaps, and general enhancements.
  7. Assign yourself as assignee

Important Note: Suggestions will be completely ignored unless accompanied with a Pull Request including all suggested changes.

Replying

When replying an issue:

  1. Writing
    1. Be kind
    2. Be brief
    3. Do NOT start another topic
    4. Mind your spelling
    5. Mind your grammar
  2. Referencing
    • Reference related issues
    • Reference Pull Request addressing the problem
    • Reference commits addressing the problem
    • Reference branch/file/line-number when quoting
  3. Clean the visual garbage
    • Replying from mail? Remove the tail!
    • No signatures
    • No greetings
    • No goodbye
    • No names, teams, cheering, etc.

Important Note: Writing consistent rules takes one hundred times more time than expressing an opinion. All you write down can be used (and will be) to request you a Pull Request.