a bit more docs, changelog for #518