Merge pull request #466 from jwtk/449-doc-help

Issue 449: updated docs to better clarify help and contributing.

README.md

@@ -1,5 +1,6 @@
 [![Build Status](https://travis-ci.org/jwtk/jjwt.svg?branch=master)](https://travis-ci.org/jwtk/jjwt)
 [![Coverage Status](https://coveralls.io/repos/github/jwtk/jjwt/badge.svg?branch=master)](https://coveralls.io/github/jwtk/jjwt?branch=master)
+[![Gitter](https://badges.gitter.im/jwtk/jjwt.svg)](https://gitter.im/jwtk/jjwt?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge)
 
 ## Java JWT: JSON Web Token for Java and Android
 
@@ -17,13 +18,20 @@ and is supported and maintained by a [community](https://github.com/jwtk/jjwt/gr
 
 [Okta](https://developer.okta.com/) is a complete authentication and user management API for developers.
 
-We've also added some convenience extensions that are not part of the specification, such as JWT compression and claim 
+We've also added some convenience extensions that are not part of the specification, such as JWS compression and claim 
 enforcement.
 
 ## Table of Contents
 
 * [Features](#features)
   * [Currently Unsupported Features](#features-unsupported)
+* [Community](#community)
+  * [Getting Help](#help)
+    * [Questions](#help-questions)
+    * [Bugs and Feature Requests](#help-issues)
+  * [Contributing](#contributing)
+    * [Pull Requests](#contributing-pull-requests)
+    * [Help Wanted](#contributing-help-wanted)
 * [What is a JSON Web Token?](#overview)
 * [Installation](#install)
   * [JDK Projects](#install-jdk)
@@ -110,6 +118,79 @@ enforcement.
 
 These features will be implemented in a future release.  Community contributions are welcome!
 
+<a name="community"></a>
+## Community
+
+<a name="help"></a>
+### Getting Help
+
+If you have trouble using JJWT, please first read the documentation on this page before asking questions.  We try 
+very hard to ensure JJWT's documentation is robust, categorized with a table of contents, and up to date for each release.
+
+<a name="help-questions"></a>
+#### Questions
+
+If the documentation or the API JavaDoc isn't sufficient, and you either have usability questions or are confused
+about something, please [ask your question here](https://stackoverflow.com/questions/ask?tags=jjwt&guided=false).
+
+After asking your question, you may wish to join our [Slack](https://jwtk.slack.com/messages/CBNACTN3A) or
+[Gittr](https://gitter.im/jwtk/jjwt) chat rooms, but note that they may not always be attended. You will usually
+have a better chance of having your question answered by 
+[asking your question here](https://stackoverflow.com/questions/ask?tags=jjwt&guided=false).
+   
+If you believe you have found a bug or would like to suggest a feature enhancement, please create a new GitHub issue, 
+however:
+
+**Please do not create a GitHub issue to ask a question.**  
+
+We use GitHub Issues to track actionable work that requires changes to JJWT's design and/or codebase.  If you have a 
+usability question, instead please 
+[ask your question here](https://stackoverflow.com/questions/ask?tags=jjwt&guided=false), or try Slack or Gittr as 
+described above.
+
+**If a GitHub Issue is created that does not represent actionable work for JJWT's codebase, it will be promptly closed.**
+
+<a name="help-issues"></a>
+#### Bugs and Feature Requests
+
+If you do not have a usability question and believe you have a legitimate bug or feature request, 
+please do [create a new JJWT issue](https://github.com/jwtk/jjwt/issues/new).
+
+If you feel like you'd like to help fix a bug or implement the new feature yourself, please read the Contributing 
+section next before starting any work.
+
+<a name="contributing"></a>
+### Contributing
+
+<a name="contributing-pull-requests"></a>
+#### Pull Requests
+
+Simple Pull Requests that fix anything other than JJWT core code (documentation, JavaDoc, typos, test cases, etc) are 
+always appreciated and have a high likelihood of being merged quickly. Please send them!
+
+However, if you want or feel the need to change JJWT's functionality or core code, please do not issue a pull request 
+without [creating a new JJWT issue](https://github.com/jwtk/jjwt/issues/new) and discussing your desired 
+changes **first**, _before you start working on it_.
+
+It would be a shame to reject your earnest and genuinely appreciated pull request if it might not not align with the 
+project's goals, design expectations or planned functionality.  We've sadly had to reject large PRs in the past because
+they were out of sync with project or design expectations - all because the PR author didn't first check in with 
+the team first before working on a solution.
+
+So, please [create a new JJWT issue](https://github.com/jwtk/jjwt/issues/new) first to discuss, and then we can see if
+(or how) a PR is warranted.  Thank you!
+
+<a name="contributing-help-wanted"></a>
+#### Help Wanted
+
+If you would like to help, but don't know where to start, please visit the 
+[Help Wanted Issues](https://github.com/jwtk/jjwt/labels/help%20wanted) page and pick any of the 
+ones there, and we'll be happy to discuss and answer questions in the issue comments.
+
+If any of those don't appeal to you, no worries! Any help you would like to offer would be 
+appreciated based on the above caveats concerning [contributing pull reqeuests](#contributing-pull-requests). Feel free
+to discuss or ask questions first if you're not sure. :)
+
 <a name="overview"></a>
 ## What is a JSON Web Token?