diff --git a/docs/help-typer.md b/docs/help-typer.md index b5c0dd2..98cf406 100644 --- a/docs/help-typer.md +++ b/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): https://github.com/tiangolo/typer. @@ -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. * Follow me on **Twitter**. * Tell me how you use Typer (I love to hear that). - * Ask questions. + * Hear when I make announcements or release new tools. * Connect with me on **Linkedin**. - * 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 **Dev.to**. - * On **Medium**. + * Hear when I make announcements or release new tools (although I use Twitter more often 🤷‍♂). +* Read what I write (or follow me) on **Dev.to** or **Medium**. + * Read other ideas, articles, and read about tools I have created. + * Follow me to read when I publish something new. ## Tweet about **Typer** Tweet about **Typer** 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 -* On **Twitter**. -* On **Linkedin**. -* On **Dev.to**. -* On **Medium**. +You can try and help others with their questions in: -## Help others with issues in GitHub +* GitHub Discussions +* GitHub Issues -You can see existing issues and try and help others. +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 + +For most of the cases and most of the questions there's something related to the person's **original code**. + +In many cases they will only copy a fragment of the code, but that's not enough to **reproduce the problem**. + +* You can ask them to provide a minimal, reproducible, example, 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): https://github.com/tiangolo/typer. -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 solving those issues. +Then you can try and help them solve those questions. -## Create issues +## Ask Questions -You can create a new issue in the GitHub repository, for example to: +You can create a new question in the GitHub repository, for example to: -* Report a bug/issue. -* Suggest a new feature. -* Ask a question. +* 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. 🤗 + +--- + +Here's what to have in mind and how to review a pull request: + +### Understand the problem + +* 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 create a Pull Request, 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 👥 FastAPI and Friends Discord chat server 👥 and hang out with others in the community. There's a `#typer` channel. + +!!! tip + For questions, ask them in GitHub Discussions, 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