DOC: improve contributing docs, make nicer to read and add explicit s…

…etup instructions.

Giving credit to https://github.com/pcdshub/happi/blob/master/CONTRIBUTING.rst,
where most of the content is copied from. This new doc takes
the relevant info from pydm's original page and applies it to happi's page
(which imo is a more useful page)

CONTRIBUTING.md

@@ -1,30 +1,115 @@
-# Contributing
+============
+Contributing
+============
 
-## Getting Started
+Contributions are welcome, and they are greatly appreciated! Every little bit
+helps, and credit will always be given.
 
-* Make sure you have a [GitHub account](https://github.com/signup/free)
-* Submit a ticket for your issue, assuming one does not already exist.
-  * Clearly describe the issue including steps to reproduce when it is a bug.
-  * Make sure you fill in the earliest version that you know has the issue.
-* Fork the repository on GitHub
+You can contribute in many ways:
 
+Types of Contributions
+----------------------
 
-## Making Changes
+Report Bugs
+~~~~~~~~~~~
 
-* Create a topic branch from where you want to base your work.
-  * This is usually the master branch.
-  * Only target release branches if you are certain your fix must be on that
-    branch.
-  * To quickly create a topic branch based on master; `git checkout -b
-    fix/master/my_contribution master`. Please avoid working directly on the
-    `master` branch.
-* Make commits of logical units.
-* Check for unnecessary whitespace with `git diff --check` before committing.
-* Make sure your commit messages are in the proper format (see below)
-* Make sure you have added the necessary tests for your changes.
-* Run _all_ the tests to assure nothing else was accidentally broken.
+Report bugs at https://github.com/slaclab/pydm/issues.
 
-### Writing the commit message
+If you are reporting a bug, please try to include:
+
+* Any details about your local setup that might be helpful in troubleshooting.
+* Detailed steps to reproduce the bug, including the earliest version you know has the issue.
+
+Fix Bugs
+~~~~~~~~
+
+Look through the GitHub issues for bugs. Anything tagged with "bug"
+is open to whoever wants to implement it.
+
+Implement Features
+~~~~~~~~~~~~~~~~~~
+
+Look through the GitHub issues for features. Anything tagged with "feature"
+is open to whoever wants to implement it.
+
+Write Documentation
+~~~~~~~~~~~~~~~~~~~
+
+pydm could always use more documentation, whether
+as part of the official docs, in docstrings,
+or even on the web in blog posts, articles, and such.
+
+Submit Feedback
+~~~~~~~~~~~~~~~
+
+The best way to send feedback is to file an issue at https://github.com/slaclab/pydm/issues.
+
+If you are proposing a feature:
+
+* Explain in detail how it would work.
+* Keep the scope as narrow as possible, to make it easier to implement.
+* Remember that this is a volunteer-driven project, and that contributions
+  are welcome :)
+
+Get Started!
+------------
+
+Ready to contribute? Here's how to set up `pydm` for local development.
+
+1. Fork the `pydm` repo on GitHub.
+2. Clone your fork locally::
+
+    $ git clone [email protected]:your_username_here/pydm.git
+
+3. Install your local copy into a new conda environment. Assuming you have conda installed, this is how you set up your fork for local development::
+
+    $ conda create -n pydm-environment python=3.8 pyqt=5.12.3 pip numpy scipy six psutil pyqtgraph -c conda-forge
+    $ cd pydm/
+    $ pip install -e .
+
+4. Install additional packages only needed for development and building the docs::
+
+    $ pip install -r dev-requirements.txt
+    $ pip install -r docs-requirements.txt
+
+5. Create a branch for local development::
+
+    $ git checkout -b name-of-your-bugfix-or-feature
+
+   Now you can make your changes locally.
+
+6. Install and enable ``pre-commit`` for this repository::
+
+    $ pip install pre-commit
+    $ pre-commit install
+
+7. Add new tests for any additional functionality or bugs you may have discovered.  And, of course, be sure that all previous tests still pass by running::
+
+    $ python run_tests.py
+
+8. Commit your changes and push your branch to GitHub::
+
+    $ git add .
+    $ git commit -m "Your detailed description of your changes."
+    $ git push origin name-of-your-bugfix-or-feature
+
+9. Submit a pull request through the GitHub website.
+
+Pull Request Guidelines
+-----------------------
+
+When you submit a pull request, check that it meets these guidelines:
+
+1. Try to keep pull requests small.
+2. Make frequent but logical commits, and follow the commit-message guildlines below.
+3. Fix any formatting/linting issues that pre-commit finds. (pre-commit should prevent you from commiting if you don't)
+4. All algorithms need documentation! Don't forget the .rst files in the /docs directory.
+5. Most pull request should include tests.
+6. Check the GitHub Actions status and make sure that the tests pass for all supported Python versions and platforms.
+7. Don't take requests to change your code personally!
+
+Commit Message Guidelines
+-------------------------
 
 Commit messages should be clear and follow a few basic rules. Example:
 
@@ -60,18 +145,4 @@ Standard acronyms to start the commit message with are:
 |STY | style fix (whitespace, PEP8)                       |
 |TST | addition or modification of tests                  |
 |REL | related to releasing numpy                         |
-|WIP | Commit that is a work in progress                  |
-
-## The Pull Request
-
-* Now push to your fork
-* Submit a [pull request](https://help.github.com/articles/using-pull-requests) to this branch. This is a start to the conversation.
-
-At this point you're waiting on us. We like to at least comment on pull requests within three business days 
-(and, typically, one business day). We may suggest some changes or improvements or alternatives.
-
-Hints to make the integration of your changes easy (and happen faster):
-- Keep your pull requests small
-- Don't forget your unit tests
-- All algorithms need documentation, don't forget the .rst file
-- Don't take changes requests to change your code personally
+|WIP | Commit that is a work in progress                  |