Rewrite CONTRIBUTING.rst (fix twisted#342)

* Address target group
* Use CONTRIBUTING.rst for contributors only
* Provide step-by-step instructions which can be used as a checklist
* Add newsfragment

CONTRIBUTING.rst

@@ -0,0 +1,138 @@
+Contributing to towncrier
+=========================
+
+Want to contribute to this project? Great! We'd love to hear from you!
+
+As a developer and user, you probably have some questions about our
+project and how to contribute.
+In this article we try to answer these and give you some recommendations.
+
+
+Ways to contribute
+------------------
+
+There are several options to contribute to this project:
+
+* Open a new topic on our `GitHub discussion <gh_discussions>`_ page.
+
+  Tell us about your ideas or ask questions there.
+  Discuss with us the next Towncrier release.
+
+* Help or comment on our GitHub `issues`_ tracker.
+
+  There are certainly many issues where you can help with your expertise.
+  Or you would like to share your ideas with us.
+
+* Open a new `issue <issues>`_.
+
+  If you found a bug or have a new cool feature, describe your findings.
+  Try to be as descriptive as possible to help us understand your issue.
+
+* :ref:`Modify the code <modify_code>`.
+
+  If you would love to see the new feature in the next release, this is
+  probably the best way.
+
+
+.. _modify_code:
+
+Modifying the Code
+------------------
+
+The source code is managed using Git and is hosted on GitHub::
+
+    https://github.com/twisted/towncrier
+    [email protected]:twisted/towncrier.git
+
+
+We recommend the following workflow:
+
+#. Fork our project on GitHub using this link:
+   https://github.com/twisted/towncrier/fork
+
+#. Clone your forked Git repository (replace ``GITHUB_USER`` with your
+   account name on GitHub)::
+
+   $ git clone [email protected]:GITHUB_USER/python-semver.git
+
+
+#. In your local repository create a pull request:
+
+   a. Create a new branch with::
+
+      $ git checkout -b <BRANCH_NAME>
+
+   b. Write your test cases and run the complete test suite, see :ref:`testsuite`
+      for details.
+
+   c. Document any user facing changes in the ``README.rst`` file.
+
+   d. Create a newsfragment in ``src/towncrier/newsfragments/``.
+
+   e. Create a `pull request`_.
+      Describe in the pull request what you did and why. If you have open questions, ask.
+
+#. Wait for feedback. If you receive any comments, address these.
+
+#. After your pull request got accepted, delete your branch.
+
+
+.. _testsuite:
+
+Running the Test Suite
+----------------------
+
+We use the default unittest module and `tox`_ to run tests against all supported
+Python versions and operation systems. All test dependencies are resolved
+automatically.
+
+You can decide to run the complete test suite or only part of it:
+
+* To run all tests, use::
+
+    $ tox
+
+  If you have not all Python interpreters installed on your system
+  it will probably give you some errors (``InterpreterNotFound``).
+  To avoid such errors, use::
+
+     $ tox --skip-missing-interpreters
+
+  It is possible to use one or more specific Python versions. Use the ``-e``
+  option and one or more abbreviations (``py36-tests`` for Python 3.6, ``py37-tests`` for
+  Python 3.7 etc.)::
+
+      $ tox -e py36-tests
+      $ tox -e py36-tests,py37-tests
+
+  To get a complete list and a short description, run::
+
+      $ tox -av
+
+* To run only a specific test only, use the ``towncrier.test.FILE.CLASS.METHOD`` syntax.
+
+  For example, the following line tests only the method
+  ``test_version`` in the class ``InvocationTests`` of the file ``test_project.py``
+  for all Python versions::
+
+      $ tox -- towncrier.test.test_project.InvocationTests.test_version
+
+  You can combine the specific test function with the ``-e`` option, for
+  example, to limit the tests for Python 3.6 and 3.7 only::
+
+      $ tox -e py36-tests,py37-tests -- \
+        towncrier.test.test_project.InvocationTests.test_version
+
+Our code is checked against formatting issues with `flake8`_ issues.
+It is recommended to run your tests in combination with the ``flake8`` target::
+
+  $ tox -e flake8
+
+
+.. ### Links
+
+.. _flake8: https://flake8.rtfd.io
+.. _gh_discussions: https://github.com/twisted/towncrier/discussions
+.. _issues:  https://github.com/twisted/towncrier/issues
+.. _pull request: https://github.com/twisted/towncrier/pulls
+.. _tox: https://tox.rtfd.org/

src/towncrier/newsfragments/342.doc.rst

@@ -0,0 +1 @@
+Improve ``CONTRIBUTING.rst`` file