opentf/BUG_REPORTS.md

OpenTofu Bug Report Process

This document describes this project's typical process for posting, triaging, and responding to bug reports.

The main purpose of this documentation is to help contributors know what they might expect when they open an bug report. However, this is intentionally a primarily-human-driven process where maintainers aim to be pragmatic and adjust as needed when something doesn't fit the process well. This is not a set of rules that we expect to follow unquestioningly in all cases.

🐞 To share a bug report, open a GitHub issue. We don't expect everyone who opens a bug report to read the rest of this document, but the following text includes some tips that might help us to act on your bug report more quickly.

What is a "bug" anyway?

For the sake of this document, "bug" mainly describes a situation where OpenTofu is behaving in a different way than it was designed to behave, and thus the typical way to resolve a bug is to change the implementation to match the originally-intended design, rather than to change the design.

However, there is often some ambiguity about what exactly the design intention was, and that's particularly true for features that OpenTofu inherited from its predecessor where the current maintainers were not directly involved in the design process. In such cases we will need to make a judgement call about whether something was intended behavior or not.

We distinguish "bug" from "enhancement" mainly because each requires a different kind of response. Whereas addressing a bug is primarily about changing the implementation to match a pre-existing design intention, an enhancement request asks us to consider changing the design to support a new use-case or new workflow. Enhancement requests typically have the extra step of deciding exactly what design change to make, which requires following a different process.

The Fast Path

The "fast path" is intended to allow us to respond quickly to clear and unambiguous bug reports without getting so bogged down in discussion and consensus-building.

The fast path can apply to any bug where all of the following are true:

• The original report contains enough information for a maintainer to reproduce the described behavior on their own computer, and a maintainer has successfully done so.
• The observed behavior clearly contradicts a statement made in the OpenTofu documentation, or in other documentation-like sources like the -help output of a command or a previously-accepted RFC whose proposal hasn't been superseded by a later RFC.
• There is a relatively-obvious, low-risk way to change the implementation to match what the documentation described, without affecting the behavior of any other features or introducing new capabilities that would be subject to OpenTofu's compatibility promises.

For any bug report that is eligible for the fast path, any individual OpenTofu maintainer can post a comment describing exactly what steps they took to reproduce the described behavior, what documentation (or similar) they are citing to justify it not matching the design intention, and the specific change they propose to fix it. They can then immediately mark the bug report as "accepted" without waiting for the usual triage and consensus process, and optionally prepare a pull request implementing their proposed fix.

This is therefore a asynchronous process that allows a single maintainer to act completely autonomously aside from the code review step. The code review step still provides an opportunity for other maintainers to ask for the issue to return to the longer path for deeper discussion when appropriate, but we prefer to bias toward fast acceptance whenever things seem uncontroversial.

As a bug reporter, you can help a bug to be handled quickly by doing your best to provide the information that could justify fast path eligibility as described above in your original bug report text, in which case a maintainer need only confirm that they were able to follow your reproduction steps and that any proposed fix is self-contained and low-risk enough.

The Longer Path

For any bug report that is not eligible for the fast path, maintainers and other participants need to collaborate in comments on the issue to try to answer at least the following questions:

• Can anyone other than the original reporter reliably reproduce the described behavior? If not, can we explain why? (e.g. perhaps it requires running on a specific network where OpenTofu would be interacting with some unusual network equipment.)
• Does the described behavior seem to match the design intention for the relevant features? If so, should we transform the report into an enhancement request to discuss changing OpenTofu's design, or should we close the issue?
• Is a localized fix for the bug possible, or does something else in the broader system need to change too?
• Is there any way to work around the problem in the meantime, using the current OpenTofu implementation unmodified?

Hopefully, discussion on the issue will introduce enough new information to make the issue belatedly eligible for the fast path, in which case we can proceed as in the previous section.

For all other cases, the maintainers will discuss the situation in periodic synchronous meetings and try to find consensus for what action to take. The maintainers might either find consensus immediately, or they might identify some additional questions to ask to gather more information in order to help make a decision. In either case, a representative of the maintainer team will post a comment on the issue describing the result of that discussion.

In hopefully-unusual cases we may not be able to make a decision at all for some reason, such as if a bug is not reliably reproducible and we run out of ideas for what might be causing it. In that case, we will eventually close the issue with a comment to that effect but remain willing to reopen it if someone is able to provide new information that might unblock it, in which case the discussion and consensus process continues with that new information.

Once a Bug Report is "Accepted"

Whether it happens asynchronously by fast-path or it requires more extensive discussion, the intended goal is for a bug report issue to eventually be marked as "accepted", using a GitHub issue label.

Once a bug report reaches that state, the maintainer that marked it as such will leave a comment describing what was accepted -- that is, what specific solutions the maintainers have decided to accept -- and pin that comment to make it more visible.

For accepted issues we welcome code contributions from the community as described in Contributing to OpenTofu, unless the acceptance comment stated otherwise. Thanks!

When a Bug Report Becomes an Enhancement Request

Sometimes we will find that the behavior described in a bug report matches what was documented, in which case we will typically try to reinterpret the bug report as an enhancement request to meet a new use-case that OpenTofu was not previously designed to support well.

The full process for enhancement requests its beyond the scope of this document, but the main thing to know is that when maintainers switch into this mode the type of discussion is likely to switch to understanding more about what the requester was trying to achieve and considering various different possible solutions to meet that goal so that the maintainers can make design tradeoffs.

Reclassifying a bug report issue into an enhancement request issue does not imply a change in the priority of addressing it, but instead just recognizes that a different type of work is needed: product research and technical design, rather than simply code debugging and repair.