Add historical/upgrade-related documentation

[moutons]

Users who upgrade the audit cookbook may experience different behavior depending on which version of the cookbook they upgraded from, as settings and compatibility changed. The compatibility matrix helps smooth bumps in the road somewhat, but there's not a good place to go other than spelunking through git history to find out what might have changed from one version to another. The particular issue which brought this to mind was the change from array of hashes to hash of hashes in #358, but there may be others I'm not thinking of at the moment. Not all cases are handled with graceful errors in the code, and it seems like a decent idea to have a spot to note these sorts of things.

Where would be a good place to do this? In the README? In a TROUBLESHOOTING.md file? Some other thing?

[welcomebot]

Hey There
It looks like this is the first issue you've filed against the chef-cookbooks project. I'm here to offer you a bit of extra help to make sure we can quickly get back to you.
Make sure you've filled out all the fields in our issue template. Make sure you've provided us with the version of chef-client you're running, your operating system and the version of the cookbook. If you're not using the most up to date version of the cookbook then please make sure to update first. Lots of things change between versions even if you're issue isn't listed in the changelog. Finally please give us a detailed description of the issue you're having. The more we know about what you're trying to do, what actually happens, and how you can reproduce the problem, the better.

If you're looking for more immediate troubleshooting help make sure to check out #general on the Chef Community Slack. There's plenty of folks there willing to lend a helping hand. Thanks for the first issue. We hope we can get back to you soon with a solution.

[clintoncwolfe]

Thanks for pointing this out. I agree this could be a lot more accessible and obvious.

On the plus side, I do think the info is there in one place (in the CHANGELOG.md), though it would take a lot of insider knowledge to sift out the relevant parts and - most importantly - add practical migration / remediation steps.