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

Co-authored-by: Adi Roiban <[email protected]>

CONTRIBUTING.rst

@@ -0,0 +1,132 @@
+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 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 using GitHub `issues`_ tracker.
+
+  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.
+
+* Check out the Freenode ``#twisted-dev`` IRC channel.
+
+  If you prefer to discuss some topics personally, you may find the IRC
+  channel interesting.
+
+* Modify the 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 the section
+      *Running the test suite* for details.
+
+   c. Document any user facing changes in the ``README.rst`` file.
+
+   d. Create a newsfragment in ``src/towncrier/newsfragments/`` describing the changes and containing information that are of interest for end-users.
+
+   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 `twisted.trial`_ module and `tox`_ to run tests against all supported
+Python versions and operation systems. All test dependencies are resolved
+automatically.
+
+The following list contains some ideas how to run the test suite:
+
+* To run all tests, use::
+
+    $ tox
+
+  You may want to add the ``--skip-missing-interpreters`` option to avoid erros
+  when a specific Python interpreter version couldn't be found.
+
+*  To get a complete list about the available targets, run::
+
+    $ tox -av
+
+* To run only a specific test only, use the ``towncrier.test.FILE.CLASS.METHOD`` syntax,
+  for example::
+
+    $ tox -- towncrier.test.test_project.InvocationTests.test_version
+
+* To run some quality checks before you create the pull request,
+  we recommend to use this call::
+
+    $ tox -e flake8,check-manifest,check-newsfragment
+
+* To investigate and debug errors, use the ``trial`` command like this::
+
+    $ trial -b towncrier
+
+  This command creates a virtual environment and invokes a PDB session.
+
+
+
+.. ### Links
+
+.. _flake8: https://flake8.rtfd.io
+.. _GitHub 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/
+.. _twisted.trial: https://twistedmatrix.com/trac/wiki/TwistedTrial

src/towncrier/newsfragments/342.doc.rst

@@ -0,0 +1 @@
+Improve ``CONTRIBUTING.rst`` and add PR template.