Consider adding another group for "known issues"

[headcr4sh]

It might happen, that a software is released and it is desirable to inform the users about "known issues" and possible workarounds. I therefore think that it might be a nice idea to introduce a new group, e.g.:

## [0.1.42] - 2015-04-27
### Added
- Application can now be used by cats.
### Known Issues
- Application might scare your cat. [Workaround: Talk to your cat and explain the situation]

A "Known issues" section differs a lot from the other sections and one might argue, that such information is better kept in a separate TODO.md. On the other hand... I think, that TODO files are for developers, whereas a CHANGELOG should ideally be the only source of information for users.

[mbrand12]

I like this idea, it makes sense to me, especially if the issue is persistent and problematic to change until the next major release, as an added benefit of the GitHub it might even link to a specific Issue. It also works well with the existing spec, since when the issue is fixed it will be filed under Fixed. Though this should not be abused by listing every issue and such.

[olivierlacan]

This is interesting. @headcr4sh, would you append this information once issues have been discovered in release versions? That makes a lot of sense to me and would provide a clear resolution path for people, since they could easily bump to whichever subsequent release mentions a fix to the previously known issue.

[headcr4sh]

@olivierlacan I think indeed, that it makes sense to append this information to previously released versions. How one should link "fixes" to "linked issues" in a standard way is an interesting question... does Markdown support some kind of "anchors" that might be used here?

[svetlyak40wt]

@headcr4sh there isn't but nothing prevent you from inserting raw HTML anchors, how this answer on the stackoverflow suggests.

[headcr4sh]

@svetlyak40wt Thanks for the link.
Raw HTML anchors seem indeed like a nice solution when it comes to linking known issues with their resolution-counterparts.

[Leif-W]

I like this. I was trying to think of a general term to convey pertinent information about things that didn't fit into the other categories.

Situation: push out an update to old code to quickly return the code to usability and address security issues, while temporarily removing some significant, but infrequently used "bells and whistles" functionality while it gets an overhaul (changing libs), to let users know the functionality will return soon once rewritten, but that the timely return to basic functionality and security fix was deemed more important.

I place notes in Changed to indicate what area has the reduced functionality, Removed to let them know what was removed and (briefly) why, Security to let them know why it was removed (in detail), and now Known Issues to let them know it will return.

Redundant, but I never know what section people might focus on or ignore, so at least this way, no matter where they focus, they get part of the story, and can understand the whole story if they read all sections, to understand the change, the reason, and the plan. Does this seem like a valid use case?

It didn't seem like a good idea to venture into a "Coming Soon" group, as a vaporware doesn't belong in a Changelog, but for something that already existed, that needs to come back, maybe that is a candidate to be addressed by "Known Issues".

Anyways, thanks again for working on this project. It has helped me to better appreciate the construction of a quality Changelog, and begin to formalize a crucial, often overlooked, and rather haphazard process.

[saden1]

I would love to see "known issues" as a standard section in change logs. Having such a section will:

1. inform readers about issues that have been discovered that have not been addressed yet.
2. remind developers and stakeholders issues that require their attention.

[gilmrjc]

Why do you need to log this known issues? A change log server to document what happened to the project. Are this known issues added, changed or removed? The known issues are not made, are discovered and they belong to a tracking system in the form of open issues.

If they are outstanding bugs or something marked as won't-fix they should be on the README, not the CHANGELOG. I'll give you an example, a common practice for frontend javascript projects is to explicitly state the supported browser at the top of their README's. If one of this packages is used in a not supported browser, it will break and it is a known issue.

If it's a know issue that is going to be fixed soon, you should put that on a ROADMAP, not the change log. If you removed a feature because it is going to be refactored, mark it as removed and added at appropriate releases.

Again, a change log documents what happened, not what is going to happen.

[Leif-W]

Known Issues remain valid in the case of distributed tarballs on systems that may not be online. It is not a comprehensive list of every little bug, and requires much less overhead to maintain. Sometimes a known issue may be known at design time, such as something that will remain unimplemented in the current branch or patch release cycle. Rather than having bits and pieces of relevant info in README, in some source code management system, or in ROADMAP, it seems better to put the info in a single place where people are frequently going to look for related information.

[oinkbark]

Maybe a "Discoveries" or "Ignoring" section. Since you are not doing anything about the issue, and those words follow the format of the others a bit better

[headcr4sh]

I think there is a fundamental mis-understanding about what a known issue might be about.
Once a software has been released with a specific version it is -- usually -- desirable that no known issues are part of the release. Since software cannot be tested on all possible platforms or with every possible configuration option it might be possible though, that certain workarounds are necessary to perform the installation or certain restrictions are inevitable.

I think I'll best try to construct a legit real-world-like example (my first fictional cat-app example doesn't seem to do the trick...):

## 1.0.2 - 2019-02-10
### Additions
- TLS is now enabled for all all outgoing Web Socket connections in the client app
### Known issues
- Some Linux distributions ship with a broken set of root CAs. If the authenticity of the server's TLS certificate cannot be validated, it may be necessary, to install an updated set of root CAs under the correct location

another example

## 1.2.3 - 2019-02-10
### Fixes
- [...]
### Known issues
- On Windows systems prior to version 1809 the installater requires administrative privileges and will silently shutdown if run from within an unprivileged user account

## 2.0.4 - 2019-02-10
### Knwon issues
- Magic Mojo virus scanner reports a false positive and classifies the Windows installer as malware. A ticket in Magic Mojo's bug tracker has been created: ___LINK_TO_BUGTRACKER___

So...
... known issues are theses real annoying things that are relevant to a large subset of users. Usually there are workarounds (skip this version, perform some manual steps after installation,...) to mitigate the impact of these issues, though.

It is not the intention of the known issues section to list all bugs of the software, but the real annoying ones that happen to be a problem for a large subset of users for which a viable workaround exist, might offer some real benefit.

[Erotemic]

I would love to see this added to a 1.1.0 version of this spec.

However, I would recommend simplifying the "Known Issues" to "Issues".
This one-word form is more consistent with existing items in the "Types of Changes" tag list.

Either way I think the spec will benefit from addressing this case.

[Lunar2kPS]

Agreed!
I'd encourage adding a "Known Issues" or "Issues" section to the standard, this would be awesome.

I added it to my project's CHANGELOG anyways, regardless of standard or not, to help visibility on my project's current state.

[axd1967]

I largely agree. The main issue is that CHANGELOG is not an issue tracker.

Here is how I see this: CHANGELOG shows a chronological order of changes; the user will always discover recent information at the top, and more information lower if (s)he was on holiday. From that perspective , "known issues" belong at the top, so they can sink into the "current/busy/being-dealt-with" (feature and then master branch) version, and later continue to sink into their "release" section.

I don't think known issues should be part of a release section, because either they have to be repeated across every later release sections, or one has to assume that they are known and will be dealt with somehow. Problem with this approach is that the user will NOT read the entire CHANGELOG to discover very old, and still known issues. So KNOWN ISSUES should be either a separate, top section, or a separate document (maybe mentioned at the top of the CHANGELOG, and/or maybe mentioned in a release section, but it is likely that this will become routine and thus noise and thus overlooked).

It is not the mission of CHANGELOG to collect open issues, the advantage is that it is the focal point for changes, and to me it can also serve to communicate important known issues.

Listing known issues prevents users from repeatedly reporting them, draw their attention to a problem, and are an extra incentive to deal with ;-)

Personally, for small projects, I list all open issues/ideas/todo's at the top of the Changelog. ("coming soon"), just because of the ease of moving such paragraphs around in the CHANGELOG document. (which is a suspect argument...)

For larger projects it is not feasible to list all open issues. But the user will always be interested in major known issues.

The problem is that new issues/ideas pop up all the time, while a CHANGELOG is a snapshot frozen in time, so only NEW issues related to what popped up during testing of the associated release could be added to the CHANGELOG.

#89 (comment) is better: as we distribute several documents anyway, such as README, ROADMAP, CONTRIBUTING, DEVELOPERS etc, it might be better to list issues and ideas there, even if this means that such paragraphs will migrate from README (where they are open issues) to CHANGELOG (as part of a release). The question is how to reach the end user - usually, a README does not change much, or is too detailed. So separate documents ISSUES (or maybe KNOWN_ISSUES) might be better (in other words, this is outside of the scope of CHANGELOG).

I would not reduce the heading from "Known issues" to "Issues" because that will invite ambiguity: why not all issues, "why is MY issue not mentioned?" etc. (#89 (comment))

[Lunar2kPS]

@axd1967 Actually that's a great point, I was about to run into the problem you mentioned of a CHANGELOG being frozen in time, whereas bugs/known issues will pop up after release..

I like the idea of using a different markdown file to address known issues.

Also agree that "Issues" would be too ambiguous for comfort!

Thanks for the insight! :)