diff options
| -rw-r--r-- | docs/contributing.rst | 12 |
1 files changed, 12 insertions, 0 deletions
diff --git a/docs/contributing.rst b/docs/contributing.rst index 3b301842..98578ee2 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -122,6 +122,18 @@ So, specifically: * No blank line at the end. * Use Sphinx parameter/attribute documentation `syntax`_. +Because of the inherit challenges in implementing correct cryptographic +systems, we want to make our documentation point people in the right directions +as much as possible. To that end: + +* When documenting a generic interface, use a strong algorithm in examples. + (e.g. when showing a hashing example, don't use + :class:`cryptography.hazmat.primitives.hashes.MD5`) +* When giving perscriptive advice, always provide references and supporting + material. +* When there is disagreement about legitimate cryptographic experts, represent + both sides of the argument and describe the tradeoffs clearly. + When documenting a new module in the ``hazmat`` package, its documentation should begin with the "Hazardous Materials" warning: |