Add a "known incompatibilities" to docs
bdpedigo opened this issue · comments
I wonder if it would be worth listing in the documentation every time we find some compatibility issue with another package that pops up, say
I cant say that i have seen this often in other packages, but i think that is a mistake - i often end up just getting the solution in old github issues. Feels like just writing down the ones we know about would be helpful?
thoughts @daxpryce ?
So, the documentation is hard to keep up to date, while the tracker is the canonical source, and thus definitionally up to date. I'd... not recommend trying to list them in the docs. Maybe we could rig up a documentation thing that let's us specify a github search query of open issues in our project based on the date of publication, but then that still leaves the "new bugs/issues found that impact any/all versions" in an undefined state.
I guess I just feel like the tracker is the source regardless of what docs say. In my experience, what you can trust most, in descending order:
- The code as it is
- The tests as they are
- The task tracker as it is
- The devs as they remember
- The documentation as it purports
And usually the documentation is on the same level of accurate as a politician's verbal rhetoric surrounding a proposed law. And so I rarely treat it as my first-stop-shop for anything unless everything else fails first. I think software development has made me far too cynical for my years, if I'm being honest.
Anyway, I'm not against it, I just don't know if it's worth the effort over a link to our issue tracker, since that will ultimately be the ultimate truth?