Update contributing & policy information

5 files changed, 77 insertions, 26 deletions

diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst
index a4040e4..d47c825 100644
--- a/CONTRIBUTING.rst
+++ b/CONTRIBUTING.rst
@@ -2,24 +2,35 @@ Contributing
 ============
 
 First of all, thank you for your interest in contributing to pyOpenSSL!
+This project has no company backing its development therefore we're dependent on help by the community.
+
 
 Filing bug reports
 ------------------
 
 Bug reports are very welcome.
-Please file them on the Github issue tracker.
+Please file them on the GitHub issue tracker.
 Good bug reports come with extensive descriptions of the error and how to reproduce it.
 Reporters are strongly encouraged to include an `short, self contained, correct example <http://www.sscce.org/>`_.
 
+
+Security
+--------
+
+If you feel that you found a security-relevant bug that you would prefer to discuss in private, please send us a GPG_-encrypted e-mail.
+
+The maintainer can be reached at hs@ox.cx and his GPG key ID is ``0xAE2536227F69F181`` (Fingerprint: ``C2A0 4F86 ACE2 8ADC F817  DBB7 AE25 3622 7F69 F181``).
+Feel free to cross-check this information with Keybase_.
+
+
 Patches
 -------
 
-All patches to pyOpenSSL should be submitted in the form of pull requests to the main pyOpenSSL repository, ``pyca/pyopenssl``.
+All patches to pyOpenSSL should be submitted in the form of pull requests to the main pyOpenSSL repository, `pyca/pyopenssl`_.
 These pull requests should satisfy the following properties:
 
 - The branch referenced should be a `feature branch`_ focusing on one particular improvement to pyOpenSSL.
   Create different branches and different pull requests for unrelated features or bugfixes.
-- The branch referenced should have a distinctive name (in particular, please do not open pull requests for your ``master`` branch).
 - Code should follow `PEP 8`_, especially in the "do what code around you does" sense.
   One notable way pyOpenSSL code differs, for example, is that there should be three empty lines between module-level elements,and two empty lines between class-level elements.
   Methods and functions are named in ``snake_case``.
@@ -33,11 +44,28 @@ Finally, pull requests must be reviewed before merging.
 This process mirrors the `cryptography code review process`_.
 Everyone can perform reviews; this is a very valuable way to contribute, and is highly encouraged.
 
-Pull requests are merged by members of the `pyopenssl-committers team <https://github.com/orgs/pyca/teams/pyopenssl-committers>`_.
-They should, of course, keep all the requirements detailed in this document as well as the pyca/cryptography merge requirements in mind.
+Pull requests are merged by members of PyCA.
+They should, of course, keep all the requirements detailed in this document as well as the ``pyca/cryptography`` merge requirements in mind.
+
+The final responsibility for the reviewing of merged code lies with the person merging it.
+Since pyOpenSSL is a sensitive project from a security perspective, reviewers are strongly encouraged to take this review and merge process very seriously.
+
+
+Finding Help
+------------
+
+If you need any help with the contribution process, you'll find us hanging out at ``#cryptography-dev`` on Freenode_ IRC.
+You can also ask questions on our `mailing list`_.
+
+Wherever we interact, we strive to follow the `Python Community Code of Conduct`_.
 
-The final responsibility for the reviewing of merged code lies with the person merging it; since pyOpenSSL is obviously a sensitive project from a security perspective, so reviewers are strongly encouraged to take this review and merge process very seriously.
 
-.. _PEP 8: http://legacy.python.org/dev/peps/pep-0008/
+.. _GPG: http://en.wikipedia.org/wiki/GNU_Privacy_Guard
+.. _Keybase: https://keybase.io/hynek
+.. _pyca/pyopenssl: https://github.com/pyca/pyopenssl
+.. _PEP 8: https://www.python.org/dev/peps/pep-0008/
 .. _cryptography code review process: https://cryptography.io/en/latest/development/reviewing-patches/
-.. _feature branch: http://nvie.com/posts/a-successful-git-branching-model/
+.. _feature branch: https://www.atlassian.com/git/tutorials/comparing-workflows/feature-branch-workflow
+.. _freenode: https://freenode.net
+.. _`mailing list`: https://mail.python.org/mailman/listinfo/cryptography-dev
+.. _`Python Community Code of Conduct`: https://www.python.org/psf/codeofconduct/
diff --git a/INSTALL.rst b/INSTALL.rst
index eea013b..276e047 100644
--- a/INSTALL.rst
+++ b/INSTALL.rst
@@ -11,7 +11,7 @@ If you are installing in order to *develop* on pyOpenSSL, move to the root direc
 
 
 Documentation
-=============
+-------------
 
 The documentation is written in reStructuredText and built using Sphinx::
 
diff --git a/doc/index.rst b/doc/index.rst
index 7006ec6..4c15fc8 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -1,22 +1,25 @@
+=====================================
 Welcome to pyOpenSSL's documentation!
 =====================================
 
-.. topic:: Abstract
 
-   This module is a rather thin wrapper around (a subset of) the OpenSSL library.
-   With thin wrapper I mean that a lot of the object methods do nothing more than
-   calling a corresponding function in the OpenSSL library.
+pyOpenSSL is a rather thin wrapper around (a subset of) the OpenSSL library.
+With thin wrapper we mean that a lot of the object methods do nothing more than
+calling a corresponding function in the OpenSSL library.
 
 
 Contents:
+=========
 
 .. toctree::
-   :maxdepth: 3
+   :maxdepth: 2
 
    introduction
+   install
    api
    internals
 
+
 Indices and tables
 ==================
 
diff --git a/doc/install.rst b/doc/install.rst
new file mode 100644
index 0000000..a23a75e
--- /dev/null
+++ b/doc/install.rst
@@ -0,0 +1 @@
+.. include:: ../INSTALL.rst
diff --git a/doc/introduction.rst b/doc/introduction.rst
index c29f80c..41f8e59 100644
--- a/doc/introduction.rst
+++ b/doc/introduction.rst
@@ -1,17 +1,36 @@
 .. _intro:
 
+============
 Introduction
 ============
 
-The reason pyOpenSSL was created is that the SSL support in the socket module in
-Python 2.1 (the contemporary version of Python when the pyOpenSSL project was
-begun) was severely limited.  Other OpenSSL wrappers for Python at the time were
-also limited, though in different ways.  Unfortunately, Python's standard
-library SSL support has remained weak, although other packages (such as
-`M2Crypto <http://chandlerproject.org/Projects/MeTooCrypto>`_)
-have made great advances and now equal or exceed pyOpenSSL's functionality.
-
-The reason pyOpenSSL continues to be maintained is that there is a significant
-user community around it, as well as a large amount of software which depends on
-it.  It is a great benefit to many people for pyOpenSSL to continue to exist and
-advance.
+
+History
+=======
+
+pyOpenSSL was originally created by Martin Sjögren because the SSL support in the standard library in Python 2.1 (the contemporary version of Python when the pyOpenSSL project was begun) was severely limited.
+Other OpenSSL wrappers for Python at the time were also limited, though in different ways.
+
+Later it was maintained by `Jean-Paul Calderone`_ who among other things managed to make pyOpenSSL a pure Python project which the current maintainers are *very* grateful for.
+
+Over the time the standard library's ``ssl`` module improved, never reaching the completeness of pyOpenSSL's API coverage.
+Despite `PEP 466`_ many useful features remain Python 3-only and pyOpenSSL remains the only alternative for full-featured TLS code across all noteworthy Python versions from 2.6 through 3.4 and PyPy_.
+
+
+Development
+===========
+
+pyOpenSSL is collaboratively developed by the Python Cryptography Authority (PyCA_) that also maintains the low-level bindings called cryptography_.
+
+Current maintainer and release manager is `Hynek Schlawack`_.
+
+
+.. include:: ../CONTRIBUTING.rst
+
+
+.. _Jean-Paul Calderone: https://github.com/exarkun
+.. _PyPy: http://pypy.org
+.. _PEP 466: https://www.python.org/dev/peps/pep-0466/
+.. _PyCA: https://github.com/pyca
+.. _cryptography: https://github.com/pyca/cryptography
+.. _Hynek Schlawack: https://hynek.me/