Merge branch 'master' into fix_523

docs/help-typer.md

@@ -8,6 +8,16 @@ There are very simple ways to help (several involve just one or two clicks).
 
 And there are several ways to get help too.
 
+## Subscribe to the newsletter
+
+You can subscribe to the (infrequent) [**FastAPI and friends** newsletter](/newsletter/){.internal-link target=_blank} to stay updated about:
+
+* News about FastAPI and friends, including Typer 🚀
+* Guides 📝
+* Features ✨
+* Breaking changes 🚨
+* Tips and tricks ✅
+
 ## Star **Typer** in GitHub
 
 You can "star" Typer in GitHub (clicking the star button at the top right): <a href="https://github.com/tiangolo/typer" class="external-link" target="_blank">https://github.com/tiangolo/typer</a>.
@@ -20,7 +30,7 @@ You can "watch" Typer in GitHub (clicking the "watch" button at the top right):
 
 There you can select "Releases only".
 
-Doing it, you will receive notifications (in your email) whenever there's a new release (a new version) of **Typer** with bug fixes and new features.
+By doing it, you will receive notifications (in your email) whenever there's a new release (a new version) of **Typer** with bug fixes and new features.
 
 ## Connect with the author
 
@@ -33,59 +43,184 @@ You can:
     * Follow me to see when I create a new Open Source project.
 * <a href="https://twitter.com/tiangolo" class="external-link" target="_blank">Follow me on **Twitter**</a>.
     * Tell me how you use Typer (I love to hear that).
-    * Ask questions.
+    * Hear when I make announcements or release new tools.
 * <a href="https://www.linkedin.com/in/tiangolo/" class="external-link" target="_blank">Connect with me on **Linkedin**</a>.
-    * Talk to me.
-    * Endorse me or recommend me :)
-* Read what I write (or follow me):
-    * Read other ideas, articles and tools I have created.
-    * Follow me to see when I publish something new.
-    * On <a href="https://dev.to/tiangolo" class="external-link" target="_blank">**Dev.to**</a>.
-    * On <a href="https://medium.com/@tiangolo" class="external-link" target="_blank">**Medium**</a>.
+    * Hear when I make announcements or release new tools (although I use Twitter more often 🤷‍♂).
+* Read what I write (or follow me) on <a href="https://dev.to/tiangolo" class="external-link" target="_blank">**Dev.to**</a> or <a href="https://medium.com/@tiangolo" class="external-link" target="_blank">**Medium**</a>.
+    * Read other ideas, articles, and read about tools I have created.
+    * Follow me to read when I publish something new.
 
 ## Tweet about **Typer**
 
 <a href="https://twitter.com/compose/tweet?text=I'm loving Typer because... https://github.com/tiangolo/typer cc @tiangolo" class="external-link" target="_blank">Tweet about **Typer**</a> and let me and others know why you like it.
 
-## Let me know how are you using **Typer**
-
 I love to hear about how **Typer** is being used, what have you liked in it, in which project/company you are using it, etc.
 
-You can let me know:
+## Help others with questions in GitHub
+
+You can try and help others with their questions in:
+
+* <a href="https://github.com/tiangolo/typer/discussions/categories/questions?discussions_q=category%3AQuestions+is%3Aunanswered" class="external-link" target="_blank">GitHub Discussions</a>
+* <a href="https://github.com/tiangolo/typer/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3Aquestion+-label%3Aanswered+" class="external-link" target="_blank">GitHub Issues</a>
+
+In many cases you might already know the answer for those questions. 🤓
+
+Just remember, the most important point is: try to be kind. People come with their frustrations and in many cases don't ask in the best way, but try as best as you can to be kind. 🤗
+
+The idea is for the **Typer** community to be kind and welcoming. At the same time, don't accept bullying or disrespectful behavior towards others. We have to take care of each other.
+
+---
+
+Here's how to help others with questions (in discussions or issues):
+
+### Understand the question
+
+* Check if you can understand what is the **purpose** and use case of the person asking.
+
+* Then check if the question (the vast majority are questions) is **clear**.
+
+* In many cases the question asked is about an imaginary solution from the user, but there might be a **better** one. If you can understand the problem and use case better, you might be able to suggest a better **alternative solution**.
+
+* If you can't understand the question, ask for more **details**.
+
+### Reproduce the problem
 
-* <a href="https://twitter.com/compose/tweet?text=Hey @tiangolo, I'm using Typer at..." class="external-link" target="_blank">On **Twitter**</a>.
-* <a href="https://www.linkedin.com/in/tiangolo/" class="external-link" target="_blank">On **Linkedin**</a>.
-* <a href="https://dev.to/tiangolo" class="external-link" target="_blank">On **Dev.to**</a>.
-* <a href="https://medium.com/@tiangolo" class="external-link" target="_blank">On **Medium**</a>.
+For most of the cases and most of the questions there's something related to the person's **original code**.
 
-## Help others with issues in GitHub
+In many cases they will only copy a fragment of the code, but that's not enough to **reproduce the problem**.
 
-You can see <a href="https://github.com/tiangolo/typer/issues" class="external-link" target="_blank">existing issues</a> and try and help others.
+* You can ask them to provide a <a href="https://stackoverflow.com/help/minimal-reproducible-example" class="external-link" target="_blank">minimal, reproducible, example</a>, that you can **copy-paste** and run locally to see the same error or behavior they are seeing, or to understand their use case better.
+
+* If you are feeling too generous, you can try to **create an example** like that yourself, just based on the description of the problem. Just have in mind that this might take a lot of time and it might be better to ask them to clarify the problem first.
+
+### Suggest solutions
+
+* After being able to understand the question, you can give them a possible **answer**.
+
+* In many cases, it's better to understand their **underlying problem or use case**, because there might be a better way to solve it than what they are trying to do.
+
+### Ask to close
+
+If they reply, there's a high chance you would have solved their problem, congrats, **you're a hero**! 🦸
+
+* Now, if that solved their problem, you can ask them to:
+
+    * In GitHub Discussions: mark the comment as the **answer**.
+    * In GitHub Issues: **close** the issue**.
 
 ## Watch the GitHub repository
 
 You can "watch" Typer in GitHub (clicking the "watch" button at the top right): <a href="https://github.com/tiangolo/typer" class="external-link" target="_blank">https://github.com/tiangolo/typer</a>.
 
-If you select "Watching" instead of "Releases only", you will receive notifications when someone creates a new issue.
+If you select "Watching" instead of "Releases only" you will receive notifications when someone creates a new issue or question. You can also specify that you only want to be notified about new issues, or discussions, or PRs, etc.
+
+Then you can try and help them solve those questions.
 
-Then you can try and help them solving those issues.
+## Ask Questions
+
+You can <a href="https://github.com/tiangolo/typer/discussions/new?category=questions" class="external-link" target="_blank">create a new question</a> in the GitHub repository, for example to:
+
+* Ask a **question** or ask about a **problem**.
+* Suggest a new **feature**.
+
+**Note**: if you do it, then I'm going to ask you to also help others. 😉
+
+## Review Pull Requests
+
+You can help me review pull requests from others.
+
+Again, please try your best to be kind. 🤗
+
+---
 
-## Create issues
+Here's what to have in mind and how to review a pull request:
 
-You can <a href="https://github.com/tiangolo/typer/issues/new/choose" class="external-link" target="_blank">create a new issue</a> in the GitHub repository, for example to:
+### Understand the problem
 
-* Report a bug/issue.
-* Suggest a new feature.
-* Ask a question.
+* First, make sure you **understand the problem** that the pull request is trying to solve. It might have a longer discussion in a GitHub Discussion or issue.
+
+* There's also a good chance that the pull request is not actually needed because the problem can be solved in a **different way**. Then you can suggest or ask about that.
+
+### Don't worry about style
+
+* Don't worry too much about things like commit message styles, I will squash and merge customizing the commit manually.
+
+* Also don't worry about style rules, there are already automatized tools checking that.
+
+And if there's any other style or consistency need, I'll ask directly for that, or I'll add commits on top with the needed changes.
+
+### Check the code
+
+* Check and read the code, see if it makes sense, **run it locally** and see if it actually solves the problem.
+
+* Then **comment** saying that you did that, that's how I will know you really checked it.
+
+!!! info
+    Unfortunately, I can't simply trust PRs that just have several approvals.
+
+    Several times it has happened that there are PRs with 3, 5 or more approvals, probably because the description is appealing, but when I check the PRs, they are actually broken, have a bug, or don't solve the problem they claim to solve. 😅
+
+    So, it's really important that you actually read and run the code, and let me know in the comments that you did. 🤓
+
+* If the PR can be simplified in a way, you can ask for that, but there's no need to be too picky, there might be a lot of subjective points of view (and I will have my own as well 🙈), so it's better if you can focus on the fundamental things.
+
+### Tests
+
+* Help me check that the PR has **tests**.
+
+* Check that the tests **fail** before the PR. 🚨
+
+* Then check that the tests **pass** after the PR. ✅
+
+* Many PRs don't have tests, you can **remind** them to add tests, or you can even **suggest** some tests yourself. That's one of the things that consume most time and you can help a lot with that.
+
+* Then also comment what you tried, that way I'll know that you checked it. 🤓
 
 ## Create a Pull Request
 
-You can <a href="https://github.com/tiangolo/typer" class="external-link" target="_blank">create a Pull Request</a>, for example:
+You can [contribute](contributing.md){.internal-link target=_blank} to the source code with Pull Requests, for example:
 
 * To fix a typo you found on the documentation.
 * To propose new documentation sections.
 * To fix an existing issue/bug.
+    * Make sure to add tests.
 * To add a new feature.
+    * Make sure to add tests.
+    * Make sure to add documentation if it's relevant.
+
+## Help Maintain Typer
+
+Help me maintain **Typer**! 🤓
+
+There's a lot of work to do, and for most of it, **YOU** can do it.
+
+The main tasks that you can do right now are:
+
+* [Help others with questions in GitHub](#help-others-with-questions-in-github){.internal-link target=_blank} (see the section above).
+* [Review Pull Requests](#review-pull-requests){.internal-link target=_blank} (see the section above).
+
+Those two tasks are what **consume time the most**. That's the main work of maintaining Typer.
+
+If you can help me with that, **you are helping me maintain Typer** and making sure it keeps **advancing faster and better**. 🚀
+
+## Join the chat
+
+Join the 👥 <a href="https://discord.gg/VQjSZaeJmf" class="external-link" target="_blank">FastAPI and Friends Discord chat server</a> 👥 and hang out with others in the community. There's a `#typer` channel.
+
+!!! tip
+    For questions, ask them in <a href="https://github.com/tiangolo/typer/discussions/new?category=questions" class="external-link" target="_blank">GitHub Discussions</a>, there's a much better chance you will receive help there.
+
+    Use the chat only for other general conversations.
+
+### Don't use the chat for questions
+
+Have in mind that as chats allow more "free conversation", it's easy to ask questions that are too general and more difficult to answer, so, you might not receive answers.
+
+In GitHub, the template will guide you to write the right question so that you can more easily get a good answer, or even solve the problem yourself even before asking. And in GitHub I can make sure I always answer everything, even if it takes some time. I can't personally do that with the chat. 😅
+
+Conversations in the chat are also not as easily searchable as in GitHub, so questions and answers might get lost in the conversation.
+
+On the other side, there are thousands of users in the chat, so there's a high chance you'll find someone to talk to there, almost all the time. 😄
 
 ## Sponsor the author
 

docs/release-notes.md

@@ -1,5 +1,6 @@
 ## Latest Changes
 
+* 📝 Update docs about helping Typer. PR [#547](https://github.com/tiangolo/typer/pull/547) by [@tiangolo](https://github.com/tiangolo).
 * 🔧 Update new issue chooser to suggest GitHub Discussions. PR [#544](https://github.com/tiangolo/typer/pull/544) by [@tiangolo](https://github.com/tiangolo).
 * 🔧 Add GitHub Discussion templates for questions. PR [#541](https://github.com/tiangolo/typer/pull/541) by [@tiangolo](https://github.com/tiangolo).
 * 🔧 Update pre-commit, Python version, isort version. PR [#542](https://github.com/tiangolo/typer/pull/542) by [@tiangolo](https://github.com/tiangolo).