fixes #1. documented conventions and the testing env