A known issue is a problem the team already knows about. It has been reproduced, written down and usually given a ticket, but it has not been fixed in the current release. Release notes often have a section with exactly that heading.
Listing a known issue is a form of honesty. It tells users the behavior is not their fault, saves them from filing a duplicate report, and often gives a workaround. It also helps support and sales teams answer questions without guessing.
There are good reasons a bug ships as known. The fix might be risky this close to a release. It might depend on an upstream library or a vendor. It might affect a small set of users while the release fixes something that affects everyone. The release goes out with the issue documented rather than held back for it.
A useful known-issue entry has four parts: the symptom in the user’s words, which versions or setups are affected, a workaround if one exists, and a link to the issue so people can follow it. On GitHub or GitLab that is often a pinned issue or a label like known-issue, plus a line in the changelog.
The risk is that “known” turns into “permanent.” Review the list each release and either fix, re-scope or close each item with a reason. An issue that has been known for three years is a feature with poor documentation.
The shirt says “KNOWN ISSUE.” It is documented and scheduled.
In the wild
Known issue in 2.4.0: CSV export drops the time zone. Workaround is the JSON export. Fix is tracked in #812.
