📝 Update docs about helping Typer (#547)
This commit is contained in:
Sebastián Ramírez
GitHub
parent
1201e7f3b2
commit
6386bcd741
1 changed files with 161 additions and 26 deletions
|
|
@ -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
|
||||
|
||||
* <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>.
|
||||
You can try and help others with their questions in:
|
||||
|
||||
## Help others with issues in GitHub
|
||||
* <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>
|
||||
|
||||
You can see <a href="https://github.com/tiangolo/typer/issues" class="external-link" target="_blank">existing issues</a> 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 <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 solving those issues.
|
||||
Then you can try and help them solve those questions.
|
||||
|
||||
## Create issues
|
||||
## Ask Questions
|
||||
|
||||
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:
|
||||
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:
|
||||
|
||||
* 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 <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
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue