diff --git a/doc/source/contributor/bugs.rst b/doc/source/contributor/bugs.rst new file mode 100644 index 0000000000..5487887761 --- /dev/null +++ b/doc/source/contributor/bugs.rst @@ -0,0 +1,128 @@ +Bug Reporting and Triaging Guide +================================ + +StoryBoard +---------- + +All ironic projects use StoryBoard_ for tracking both bugs and enhancement +requests (RFE). The `ironic project group`_ lists all our projects. + +.. note:: + Ironic is developed as part of OpenStack and therefore uses + the ``openstack/`` namespace. + +StoryBoard is somewhat different from traditional bug tracking +systems because every *story* is not linked to a project itself, but rather +through its *tasks*. A story represents an issue you are facing or an +enhancement you want to see, while tasks represent individual action items +which can span several projects. When creating a story, you'll also need to +create the first task. If unsure, create a task against ``openstack/ironic``. + +Reporting Guide +--------------- + +We are constantly receiving a lot of requests, so it's important to file a +meaningful story for it to be acted upon. A good story: + +* specifies **why** a change is needed. +* explains how to reproduce the described condition. + + .. note:: + Please try to provide a reproducer based on unit tests, :ref:`devstack + ` or bifrost_. While we try our best to support users + using other installers and distributions, it may be non-trivial without + deep knowledge of them. If you're using a commercial distribution or + a product, please try contacting support first. + +* should be understandable without additional context. For example, if you see + an exception, we will need the full traceback. + +* should not be too verbose either. Unfortunately, we cannot process a few days + worth of system logs to find the problems, we expect your collaboration. + +* is not a question or a support request. Please see :doc:`contributing` for + the ways to contact us. + +* provides a way to contact the reporter. Please follow the comments and + expect follow-up emails, but ideally also be on IRC for questions. + +An enhancement request additionally: + +* benefits the overall project, not just one consumer. If you have a case that + is specific to your requirements, think about ways to make ironic extensible + to be able to cover it. + +* does not unnecessary increase the project scope. Consider if your idea can be + implemented without changing ironic or its projects, maybe it actually + should? + +Triaging Guide +-------------- + +The bug triaging process involves checking new stories to make sure they are +actionable by the team. This guide is mostly targeting the project team, but we +would appreciate if reporters could partly self-triage their own requests. + +* Determine if the request is valid and complete. Use the checklist in the + `Reporting Guide`_ for that. + +* Is the request a bug report or an enhancement request (an RFE)? The + difference is often subtle, the key question to answer is if the described + behavior is expected. + + Add an ``rfe`` tag to all enhancement requests and propose it for the "RFE + Review" section of the `weekly meeting`_. + +* Does the RFE obviously require a spec_? Usually this is decided when an RFE + is reviewed during the meeting, but some requests are undoubtedly complex, + involve changing a lot of critical parts and thus demand a spec. + + Add a ``needs-spec`` tag to enhancement requests that obviously need a + spec. Otherwise leave it until the meeting. + +* Apply additional tags: + + * All hardware type specific stories should receive a corresponding tag (e.g. + ``ipmi``, ``idrac``, etc). + + * API-related stories should have an ``api`` tag. + + * CI issues should have a ``gate`` tag. + +The next actions **must only** be done by a core team member (or an experienced +full-time contributor appoined by the PTL): + +* Can the RFE be automatically approved? It happens if the RFE requests an + implementation of a driver feature that is already implemented for other + drivers and does not pose additional complexity. + + If the RFE can be automatically approved, apply the ``rfe-approved`` tag. + If unsure, never apply the tag! Talk to the PTL instead. + +* Does the RFE have a corresponding spec approved? If yes, apply the + ``rfe-approved`` tag. + +* In the end, apply the ``ironic-triaged`` tag to make the story as triaged. + +Expiring Bugs +------------- + +While we hope to fix all issues that our consumers hit, it is unfortunately not +realistic. Stories **may** be closed by marking all their tasks ``INVALID`` in +the following cases: + +* No solution has been proposed in 1 calendar year. + +* Additional information has been requested from the reporter, and no update + has been provided in 1 calendar month. + +* The request no longer aligns with the direction of the project. + +.. note:: + As usual, common sense should be applied when closing stories. + +.. _StoryBoard: https://storyboard.openstack.org +.. _ironic project group: https://storyboard.openstack.org/#!/project_group/ironic +.. _bifrost: https://docs.openstack.org/bifrost +.. _spec: https://specs.openstack.org/openstack/ironic-specs/ +.. _weekly meeting: https://wiki.openstack.org/wiki/Meetings/Ironic diff --git a/doc/source/contributor/contributing.rst b/doc/source/contributor/contributing.rst index 88f8449da8..7295da9794 100644 --- a/doc/source/contributor/contributing.rst +++ b/doc/source/contributor/contributing.rst @@ -36,11 +36,13 @@ The ironic project moved from Launchpad to `StoryBoard `_ for work and task tracking. This provides an aggregate view called a "Project Group" and individual "Projects". A good starting place is the -`project group `_ +`project group `_ representing the whole of the ironic community, as opposed to the `ironic project `_ storyboard which represents ironic as a repository. +See :doc:`bugs` for more details on how we track bugs. + Internet Relay Chat 'IRC' ------------------------- diff --git a/doc/source/contributor/index.rst b/doc/source/contributor/index.rst index 136827f94c..0377bdb34b 100644 --- a/doc/source/contributor/index.rst +++ b/doc/source/contributor/index.rst @@ -12,6 +12,7 @@ project. :maxdepth: 1 Developer Contribution Guide + Bugs Reporting and Triaging Guide Setting Up Your Development Environment Priorities Specifications diff --git a/doc/source/index.rst b/doc/source/index.rst index 39d7481eeb..d62cadeeec 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -22,6 +22,8 @@ previous release of ironic, append the OpenStack release name to the URL; for example, the ``ocata`` release is available at https://docs.openstack.org/ironic/ocata/. +Found a bug in one of our projects? Please see :doc:`/contributor/bugs`. + Installation Guide ==================