Yurii Motov
1 week ago
committed by
GitHub
GitHub
55 changed files with 890 additions and 1143 deletions
@ -1 +0,0 @@ |
|||
github: [tiangolo] |
|||
@ -0,0 +1,24 @@ |
|||
name: Zizmor |
|||
|
|||
on: |
|||
push: |
|||
branches: |
|||
- main |
|||
workflow_dispatch: |
|||
|
|||
permissions: {} |
|||
|
|||
jobs: |
|||
zizmor: |
|||
name: Run zizmor |
|||
runs-on: ubuntu-latest |
|||
timeout-minutes: 5 |
|||
permissions: |
|||
security-events: write # Required for upload-sarif (used by zizmor-action) to upload SARIF files. |
|||
steps: |
|||
- name: Checkout repository |
|||
uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 |
|||
with: |
|||
persist-credentials: false |
|||
- name: Run zizmor |
|||
uses: zizmorcore/zizmor-action@b1d7e1fb5de872772f31590499237e7cce841e8e # v0.5.3 |
|||
@ -1 +0,0 @@ |
|||
Please read the [Development - Contributing](https://fastapi.tiangolo.com/contributing/) guidelines in the documentation site. |
|||
@ -1,31 +0,0 @@ |
|||
# Security Policy |
|||
|
|||
Security is very important for FastAPI and its community. 🔒 |
|||
|
|||
Learn more about it below. 👇 |
|||
|
|||
## Versions |
|||
|
|||
The latest version of FastAPI is supported. |
|||
|
|||
You are encouraged to [write tests](https://fastapi.tiangolo.com/tutorial/testing/) for your application and update your FastAPI version frequently after ensuring that your tests are passing. This way you will benefit from the latest features, bug fixes, and **security fixes**. |
|||
|
|||
You can learn more about [FastAPI versions and how to pin and upgrade them](https://fastapi.tiangolo.com/deployment/versions/) for your project in the docs. |
|||
|
|||
## Reporting a Vulnerability |
|||
|
|||
If you think you found a vulnerability, and even if you are not sure about it, please report it right away by sending an email to: [email protected]. Please try to be as explicit as possible, describing all the steps and example code to reproduce the security issue. |
|||
|
|||
I (the author, [@tiangolo](https://x.com/tiangolo)) will review it thoroughly and get back to you. |
|||
|
|||
## Public Discussions |
|||
|
|||
Please restrain from publicly discussing a potential security vulnerability. 🙊 |
|||
|
|||
It's better to discuss privately and try to find a solution first, to limit the potential impact as much as possible. |
|||
|
|||
--- |
|||
|
|||
Thanks for your help! |
|||
|
|||
The FastAPI community and I thank you for that. 🙇 |
|||
@ -1,267 +1,7 @@ |
|||
# Development - Contributing |
|||
# Contributing |
|||
|
|||
First, you might want to see the basic ways to [help FastAPI and get help](help-fastapi.md). |
|||
|
|||
## Developing |
|||
|
|||
If you already cloned the [fastapi repository](https://github.com/fastapi/fastapi) and you want to deep dive in the code, here are some guidelines to set up your environment. |
|||
|
|||
### Install requirements |
|||
|
|||
Create a virtual environment and install the required packages with [`uv`](https://github.com/astral-sh/uv): |
|||
|
|||
<div class="termy"> |
|||
|
|||
```console |
|||
$ uv sync --extra all |
|||
|
|||
---> 100% |
|||
``` |
|||
|
|||
</div> |
|||
|
|||
It will install all the dependencies and your local FastAPI in your local environment. |
|||
|
|||
### Using your local FastAPI |
|||
|
|||
If you create a Python file that imports and uses FastAPI, and run it with the Python from your local environment, it will use your cloned local FastAPI source code. |
|||
|
|||
And if you update that local FastAPI source code when you run that Python file again, it will use the fresh version of FastAPI you just edited. |
|||
|
|||
That way, you don't have to "install" your local version to be able to test every change. |
|||
|
|||
/// note | Technical Details |
|||
|
|||
This only happens when you install using `uv sync --extra all` instead of running `pip install fastapi` directly. |
|||
|
|||
That is because `uv sync --extra all` will install the local version of FastAPI in "editable" mode by default. |
|||
|
|||
/// |
|||
|
|||
### Format the code |
|||
|
|||
There is a script that you can run that will format and clean all your code: |
|||
|
|||
<div class="termy"> |
|||
|
|||
```console |
|||
$ bash scripts/format.sh |
|||
``` |
|||
|
|||
</div> |
|||
|
|||
It will also auto-sort all your imports. |
|||
|
|||
## Tests |
|||
|
|||
There is a script that you can run locally to test all the code and generate coverage reports in HTML: |
|||
|
|||
<div class="termy"> |
|||
|
|||
```console |
|||
$ bash scripts/test-cov-html.sh |
|||
``` |
|||
|
|||
</div> |
|||
|
|||
This command generates a directory `./htmlcov/`, if you open the file `./htmlcov/index.html` in your browser, you can explore interactively the regions of code that are covered by the tests, and notice if there is any region missing. |
|||
|
|||
## Docs |
|||
|
|||
First, make sure you set up your environment as described above, that will install all the requirements. |
|||
|
|||
### Docs live |
|||
|
|||
During local development, there is a script that builds the site and checks for any changes, live-reloading: |
|||
|
|||
<div class="termy"> |
|||
|
|||
```console |
|||
$ python ./scripts/docs.py live |
|||
|
|||
<span style="color: green;">[INFO]</span> Serving on http://127.0.0.1:8008 |
|||
<span style="color: green;">[INFO]</span> Start watching changes |
|||
<span style="color: green;">[INFO]</span> Start detecting changes |
|||
``` |
|||
|
|||
</div> |
|||
|
|||
It will serve the documentation on `http://127.0.0.1:8008`. |
|||
|
|||
That way, you can edit the documentation/source files and see the changes live. |
|||
|
|||
/// tip |
|||
|
|||
Alternatively, you can perform the same steps that scripts does manually. |
|||
|
|||
Go into the language directory, for the main docs in English it's at `docs/en/`: |
|||
|
|||
```console |
|||
$ cd docs/en/ |
|||
``` |
|||
|
|||
Then run `zensical` in that directory: |
|||
|
|||
```console |
|||
$ zensical serve --dev-addr 127.0.0.1:8008 |
|||
``` |
|||
|
|||
/// |
|||
|
|||
#### Typer CLI (optional) |
|||
|
|||
The instructions here show you how to use the script at `./scripts/docs.py` with the `python` program directly. |
|||
|
|||
But you can also use [Typer CLI](https://typer.tiangolo.com/typer-cli/), and you will get autocompletion in your terminal for the commands after installing completion. |
|||
|
|||
If you install Typer CLI, you can install completion with: |
|||
|
|||
<div class="termy"> |
|||
|
|||
```console |
|||
$ typer --install-completion |
|||
|
|||
zsh completion installed in /home/user/.bashrc. |
|||
Completion will take effect once you restart the terminal. |
|||
``` |
|||
|
|||
</div> |
|||
|
|||
### Docs Structure |
|||
|
|||
The documentation uses [Zensical](https://zensical.org). |
|||
|
|||
And there are extra tools/scripts in place to handle translations in `./scripts/docs.py`. |
|||
|
|||
/// tip |
|||
|
|||
You don't need to see the code in `./scripts/docs.py`, you just use it in the command line. |
|||
|
|||
/// |
|||
|
|||
All the documentation is in Markdown format in the directory `./docs/en/`. |
|||
|
|||
Many of the tutorials have blocks of code. |
|||
|
|||
In most of the cases, these blocks of code are actual complete applications that can be run as is. |
|||
|
|||
In fact, those blocks of code are not written inside the Markdown, they are Python files in the `./docs_src/` directory. |
|||
|
|||
And those Python files are included/injected in the documentation when generating the site. |
|||
|
|||
### Docs for tests |
|||
|
|||
Most of the tests actually run against the example source files in the documentation. |
|||
|
|||
This helps to make sure that: |
|||
|
|||
* The documentation is up-to-date. |
|||
* The documentation examples can be run as is. |
|||
* Most of the features are covered by the documentation, ensured by test coverage. |
|||
|
|||
#### Apps and docs at the same time |
|||
|
|||
If you run the examples with, e.g.: |
|||
|
|||
<div class="termy"> |
|||
|
|||
```console |
|||
$ fastapi dev tutorial001.py |
|||
|
|||
<span style="color: green;">INFO</span>: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) |
|||
``` |
|||
|
|||
</div> |
|||
|
|||
as Uvicorn by default will use the port `8000`, the documentation on port `8008` won't clash. |
|||
|
|||
### Translations |
|||
|
|||
Help with translations is VERY MUCH appreciated! And it can't be done without the help from the community. 🌎 🚀 |
|||
|
|||
Translation pull requests are made by LLMs guided with prompts designed by the FastAPI team together with the community of native speakers for each supported language. |
|||
|
|||
#### LLM Prompt per Language |
|||
|
|||
Each language has a directory: [https://github.com/fastapi/fastapi/tree/master/docs](https://github.com/fastapi/fastapi/tree/master/docs), in it you can see a file `llm-prompt.md` with the prompt specific for that language. |
|||
|
|||
For example, for Spanish, the prompt is at: [`docs/es/llm-prompt.md`](https://github.com/fastapi/fastapi/blob/master/docs/es/llm-prompt.md). |
|||
|
|||
If you see mistakes in your language, you can make suggestions to the prompt in that file for your language, and request the specific pages you would like to re-generate after the changes. |
|||
|
|||
#### Reviewing Translation PRs |
|||
|
|||
We don’t require approval from native speakers for translation PRs generated automatically by our translation workflow. However, you can still review them and suggest improvements to the LLM prompt for that language to make the future translations better. |
|||
|
|||
You can check the currently [existing pull requests](https://github.com/fastapi/fastapi/pulls) for your language. You can filter the pull requests by the ones with the label for your language. For example, for Spanish, the label is [`lang-es`](https://github.com/fastapi/fastapi/pulls?q=is%3Aopen+sort%3Aupdated-desc+label%3Alang-es+label%3Aawaiting-review). |
|||
|
|||
You can also review already merged translation PRs. To do this, go to the [closed pull requests](https://github.com/fastapi/fastapi/pulls?q=is%3Apr+is%3Aclosed) and filter by your language label. For example, for Spanish, you can use [`lang-es`](https://github.com/fastapi/fastapi/pulls?q=is%3Apr+is%3Aclosed+label%3Alang-es). |
|||
|
|||
When reviewing a pull request, it's better not to suggest changes in the same pull request, because it is LLM generated, and it won't be possible to make sure that small individual changes are replicated in other similar sections, or that they are preserved when translating the same content again. |
|||
|
|||
Instead of adding suggestions to the translation PR, make the suggestions to the LLM prompt file for that language, in a new PR. For example, for Spanish, the LLM prompt file is at: [`docs/es/llm-prompt.md`](https://github.com/fastapi/fastapi/blob/master/docs/es/llm-prompt.md). |
|||
|
|||
/// tip |
|||
|
|||
Check the docs about [adding a pull request review](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-request-reviews) to approve it or request changes. |
|||
|
|||
/// |
|||
|
|||
PRs with suggestions to the language-specific LLM prompt require approval from at least one native speaker. Your help here is very much appreciated! |
|||
|
|||
#### Subscribe to Notifications for Your Language |
|||
|
|||
Check if there's a [GitHub Discussion](https://github.com/fastapi/fastapi/discussions/categories/translations) to coordinate translations for your language. You can subscribe to it, and when there's a new pull request to review, an automatic comment will be added to the discussion. |
|||
|
|||
To check the 2-letter code for the language you want to translate, you can use the table [List of ISO 639-1 codes](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes). |
|||
|
|||
#### Request a New Language |
|||
|
|||
Let's say that you want to request translations for a language that is not yet translated, not even some pages. For example, Latin. |
|||
|
|||
* The first step would be for you to find other 2 people that would be willing to be reviewing translation PRs for that language with you. |
|||
* Once there are at least 3 people that would be willing to commit to help maintain that language, you can continue the next steps. |
|||
* Create a new discussion following the template. |
|||
* Tag the other 2 people that will help with the language, and ask them to confirm there they will help. |
|||
|
|||
Once there are several people in the discussion, the FastAPI team can evaluate it and can make it an official translation. |
|||
|
|||
Then the docs will be automatically translated using LLMs, and the team of native speakers can review the translation, and help tweak the LLM prompts. |
|||
|
|||
Once there's a new translation, for example if docs are updated or there's a new section, there will be a comment in the same discussion with the link to the new translation to review. |
|||
|
|||
## Automated Code and AI |
|||
|
|||
You are encouraged to use all the tools you want to do your work and contribute as efficiently as possible, this includes AI (LLM) tools, etc. Nevertheless, contributions should have meaningful human intervention, judgement, context, etc. |
|||
|
|||
If the **human effort** put in a PR, e.g. writing LLM prompts, is **less** than the **effort we would need to put** to **review it**, please **don't** submit the PR. |
|||
|
|||
Think of it this way: we can already write LLM prompts or run automated tools ourselves, and that would be faster than reviewing external PRs. |
|||
|
|||
### Closing Automated and AI PRs |
|||
|
|||
If we see PRs that seem AI generated or automated in similar ways, we'll flag them and close them. |
|||
|
|||
The same applies to comments and descriptions, please don't copy paste the content generated by an LLM. |
|||
|
|||
### Human Effort Denial of Service |
|||
|
|||
Using automated tools and AI to submit PRs or comments that we have to carefully review and handle would be the equivalent of a [Denial-of-service attack](https://en.wikipedia.org/wiki/Denial-of-service_attack) on our human effort. |
|||
|
|||
It would be very little effort from the person submitting the PR (an LLM prompt) that generates a large amount of effort on our side (carefully reviewing code). |
|||
|
|||
Please don't do that. |
|||
|
|||
We'll need to block accounts that spam us with repeated automated PRs or comments. |
|||
|
|||
### Use Tools Wisely |
|||
|
|||
As Uncle Ben said: |
|||
|
|||
<blockquote> |
|||
With great <strike>power</strike> <strong>tools</strong> comes great responsibility. |
|||
</blockquote> |
|||
|
|||
Avoid inadvertently doing harm. |
|||
|
|||
You have amazing tools at hand, use them wisely to help effectively. |
|||
To contribute code to the project, please follow the guidelines in [tiangolo.com - Contributing](https://tiangolo.com/open-source/contributing/). |
|||
|
|||
@ -1,165 +0,0 @@ |
|||
# Repository Management Tasks |
|||
|
|||
These are the tasks that can be performed to manage the FastAPI repository by [team members](./fastapi-people.md#team). |
|||
|
|||
/// tip |
|||
|
|||
This section is useful only to a handful of people, team members with permissions to manage the repository. You can probably skip it. 😉 |
|||
|
|||
/// |
|||
|
|||
...so, you are a [team member of FastAPI](./fastapi-people.md#team)? Wow, you are so cool! 😎 |
|||
|
|||
You can help with everything on [Help FastAPI - Get Help](./help-fastapi.md) the same ways as external contributors. But additionally, there are some tasks that only you (as part of the team) can perform. |
|||
|
|||
Here are the general instructions for the tasks you can perform. |
|||
|
|||
Thanks a lot for your help. 🙇 |
|||
|
|||
## Be Nice |
|||
|
|||
First of all, be nice. 😊 |
|||
|
|||
You probably are super nice if you were added to the team, but it's worth mentioning it. 🤓 |
|||
|
|||
### When Things are Difficult |
|||
|
|||
When things are great, everything is easier, so that doesn't need much instructions. But when things are difficult, here are some guidelines. |
|||
|
|||
Try to find the good side. In general, if people are not being unfriendly, try to thank their effort and interest, even if you disagree with the main subject (discussion, PR), just thank them for being interested in the project, or for having dedicated some time to try to do something. |
|||
|
|||
It's difficult to convey emotion in text, use emojis to help. 😅 |
|||
|
|||
In discussions and PRs, in many cases, people bring their frustration and show it without filter, in many cases exaggerating, complaining, being entitled, etc. That's really not nice, and when it happens, it lowers our priority to solve their problems. But still, try to breath, and be gentle with your answers. |
|||
|
|||
Try to avoid using bitter sarcasm or potentially passive-aggressive comments. If something is wrong, it's better to be direct (try to be gentle) than sarcastic. |
|||
|
|||
Try to be as specific and objective as possible, avoid generalizations. |
|||
|
|||
For conversations that are more difficult, for example to reject a PR, you can ask me (@tiangolo) to handle it directly. |
|||
|
|||
## Edit PR Titles |
|||
|
|||
* Edit the PR title to start with an emoji from [gitmoji](https://gitmoji.dev/). |
|||
* Use the emoji character, not the GitHub code. So, use `🐛` instead of `:bug:`. This is so that it shows up correctly outside of GitHub, for example in the release notes. |
|||
* For translations use the `🌐` emoji ("globe with meridians"). |
|||
* Start the title with a verb. For example `Add`, `Refactor`, `Fix`, etc. This way the title will say the action that the PR does. Like `Add support for teleporting`, instead of `Teleporting wasn't working, so this PR fixes it`. |
|||
* Edit the text of the PR title to start in "imperative", like giving an order. So, instead of `Adding support for teleporting` use `Add support for teleporting`. |
|||
* Try to make the title descriptive about what it achieves. If it's a feature, try to describe it, for example `Add support for teleporting` instead of `Create TeleportAdapter class`. |
|||
* Do not finish the title with a period (`.`). |
|||
* When the PR is for a translation, start with the `🌐` and then `Add {language} translation for` and then the translated file path. For example: |
|||
|
|||
```Markdown |
|||
🌐 Add Spanish translation for `docs/es/docs/teleporting.md` |
|||
``` |
|||
|
|||
Once the PR is merged, a GitHub Action ([latest-changes](https://github.com/tiangolo/latest-changes)) will use the PR title to update the latest changes automatically. |
|||
|
|||
So, having a nice PR title will not only look nice in GitHub, but also in the release notes. 📝 |
|||
|
|||
## Add Labels to PRs |
|||
|
|||
The same GitHub Action [latest-changes](https://github.com/tiangolo/latest-changes) uses one label in the PR to decide the section in the release notes to put this PR in. |
|||
|
|||
Make sure you use a supported label from the [latest-changes list of labels](https://github.com/tiangolo/latest-changes#using-labels): |
|||
|
|||
* `breaking`: Breaking Changes |
|||
* Existing code will break if they update the version without changing their code. This rarely happens, so this label is not frequently used. |
|||
* `security`: Security Fixes |
|||
* This is for security fixes, like vulnerabilities. It would almost never be used. |
|||
* `feature`: Features |
|||
* New features, adding support for things that didn't exist before. |
|||
* `bug`: Fixes |
|||
* Something that was supported didn't work, and this fixes it. There are many PRs that claim to be bug fixes because the user is doing something in an unexpected way that is not supported, but they considered it what should be supported by default. Many of these are actually features or refactors. But in some cases there's an actual bug. |
|||
* `refactor`: Refactors |
|||
* This is normally for changes to the internal code that don't change the behavior. Normally it improves maintainability, or enables future features, etc. |
|||
* `upgrade`: Upgrades |
|||
* This is for upgrades to direct dependencies from the project, or extra optional dependencies, normally in `pyproject.toml`. So, things that would affect final users, they would end up receiving the upgrade in their code base once they update. But this is not for upgrades to internal dependencies used for development, testing, docs, etc. Those internal dependencies or GitHub Action versions should be marked as `internal`, not `upgrade`. |
|||
* `docs`: Docs |
|||
* Changes in docs. This includes updating the docs, fixing typos. But it doesn't include changes to translations. |
|||
* You can normally quickly detect it by going to the "Files changed" tab in the PR and checking if the updated file(s) starts with `docs/en/docs`. The original version of the docs is always in English, so in `docs/en/docs`. |
|||
* `lang-all`: Translations |
|||
* Use this for translations. You can normally quickly detect it by going to the "Files changed" tab in the PR and checking if the updated file(s) starts with `docs/{some lang}/docs` but not `docs/en/docs`. For example, `docs/es/docs`. |
|||
* `internal`: Internal |
|||
* Use this for changes that only affect how the repo is managed. For example upgrades to internal dependencies, changes in GitHub Actions or scripts, etc. |
|||
|
|||
/// tip |
|||
|
|||
Some tools like Dependabot, will add some labels, like `dependencies`, but have in mind that this label is not used by the `latest-changes` GitHub Action, so it won't be used in the release notes. Please make sure one of the labels above is added. |
|||
|
|||
/// |
|||
|
|||
## Add Labels to Translation PRs |
|||
|
|||
When there's a PR for a translation, apart from adding the `lang-all` label, also add a label for the language. |
|||
|
|||
There will be a label for each language using the language code, like `lang-{lang code}`, for example, `lang-es` for Spanish, `lang-fr` for French, etc. |
|||
|
|||
* Add the specific language label. |
|||
* Add the label `awaiting-review`. |
|||
|
|||
The label `awaiting-review` is special, only used for translations. A GitHub Action will detect it, then it will read the language label, and it will update the GitHub Discussions managing the translations for that language to notify people that there's a new translation to review. |
|||
|
|||
Once a native speaker comes, reviews the PR, and approves it, the GitHub Action will come and remove the `awaiting-review` label, and add the `approved-1` label. |
|||
|
|||
This way, we can notice when there are new translations ready, because they have the `approved-1` label. |
|||
|
|||
## Merge Translation PRs |
|||
|
|||
Translations are generated automatically with LLMs and scripts. |
|||
|
|||
There's one GitHub Action that can be manually run to add or update translations for a language: [`translate.yml`](https://github.com/fastapi/fastapi/actions/workflows/translate.yml). |
|||
|
|||
For these language translation PRs, confirm that: |
|||
|
|||
* The PR was automated (authored by @tiangolo), not made by another user. |
|||
* It has the labels `lang-all` and `lang-{lang code}`. |
|||
|
|||
For PRs that update language-specific LLM prompts, confirm that: |
|||
|
|||
* The PR has the labels `lang-all` and `lang-{lang code}`. |
|||
* It is approved by at least one native speaker. |
|||
* In some cases you might need to translate several pages with new prompt to make sure it works as expected. |
|||
|
|||
If the PR meets the above conditions, you can merge it. 😎 |
|||
|
|||
## Review PRs |
|||
|
|||
* If a PR doesn't explain what it does or why, if it seems like it could be useful, ask for more information. Otherwise, feel free to close it. |
|||
|
|||
* If a PR seems to be spam, meaningless, only to change statistics (to appear as "contributor") or similar, you can simply mark it as `invalid`, and it will be automatically closed. |
|||
|
|||
* If a PR seems to be AI generated, and seems like reviewing it would take more time from you than the time it took to write the prompt, mark it as `maybe-ai`, and it will be automatically closed. |
|||
|
|||
* A PR should have a specific use case that it is solving. |
|||
|
|||
* If the PR is for a feature, it should have docs. |
|||
* Unless it's a feature we want to discourage, like support for a corner case that we don't want users to use. |
|||
* The docs should include a source example file, not write Python directly in Markdown. |
|||
* If the source example(s) file can have different syntax for different Python versions, there should be different versions of the file, and they should be shown in tabs in the docs. |
|||
* There should be tests testing the source example. |
|||
* Before the PR is applied, the new tests should fail. |
|||
* After applying the PR, the new tests should pass. |
|||
* Coverage should stay at 100%. |
|||
* If you see the PR makes sense, or we discussed it and considered it should be accepted, you can add commits on top of the PR to tweak it, to add docs, tests, format, refactor, remove extra files, etc. |
|||
* Feel free to comment in the PR to ask for more information, to suggest changes, etc. |
|||
* Once you think the PR is ready, move it in the internal GitHub project for me to review it. |
|||
|
|||
## FastAPI People PRs |
|||
|
|||
Every month, a GitHub Action updates the FastAPI People data. Those PRs look like this one: [👥 Update FastAPI People](https://github.com/fastapi/fastapi/pull/11669). |
|||
|
|||
If the tests are passing, you can merge it right away. |
|||
|
|||
## Dependabot PRs |
|||
|
|||
Dependabot will create PRs to update dependencies for several things, and those PRs all look similar, but some are way more delicate than others. |
|||
|
|||
* If the PR is for a direct dependency, so, Dependabot is modifying `pyproject.toml` in the main dependencies, **don't merge it**. 😱 Let me check it first. There's a good chance that some additional tweaks or updates are needed. |
|||
* If the PR updates one of the internal dependencies, for example the group `dev` in `pyproject.toml`, or GitHub Action versions, if the tests are passing, the release notes (shown in a summary in the PR) don't show any obvious potential breaking change, you can merge it. 😎 |
|||
|
|||
## Mark GitHub Discussions Answers |
|||
|
|||
When a question in GitHub Discussions has been answered, mark the answer by clicking "Mark as answer". |
|||
|
|||
You can filter discussions by [`Questions` that are `Unanswered`](https://github.com/tiangolo/fastapi/discussions/categories/questions?discussions_q=category:Questions+is:open+is:unanswered). |
|||
@ -0,0 +1,28 @@ |
|||
# Translations |
|||
|
|||
Translation pull requests are made by LLMs guided with prompts designed by the FastAPI team together with the community of native speakers for each supported language. |
|||
|
|||
## LLM Prompt per Language |
|||
|
|||
Each language has a directory: [https://github.com/fastapi/fastapi/tree/master/docs](https://github.com/fastapi/fastapi/tree/master/docs), in it you can see a file `llm-prompt.md` with the prompt specific for that language. |
|||
|
|||
For example, for Spanish, the prompt is at: [`docs/es/llm-prompt.md`](https://github.com/fastapi/fastapi/blob/master/docs/es/llm-prompt.md). |
|||
|
|||
If you see mistakes in your language, you can make suggestions to the prompt in that file for your language, and request the specific pages you would like to re-generate after the changes. |
|||
|
|||
PRs with suggestions to the language-specific LLM prompt require approval from at least one native speaker. Your help here is very much appreciated! |
|||
|
|||
## Request a New Language |
|||
|
|||
Let's say that you want to request translations for a language that is not yet translated, not even some pages. For example, Latin. |
|||
|
|||
* The first step would be for you to find other 2 people that would be willing to be reviewing translation PRs for that language with you. |
|||
* Once there are at least 3 people that would be willing to commit to help maintain that language, you can continue the next steps. |
|||
* Create a new discussion following the template. |
|||
* Tag the other 2 people that will help with the language, and ask them to confirm there they will help. |
|||
|
|||
Once there are several people in the discussion, the FastAPI team can evaluate it and can make it an official translation. |
|||
|
|||
Then the docs will be automatically translated using LLMs, and the team of native speakers can review the translation, and help tweak the LLM prompts. |
|||
|
|||
Once there's a new translation, for example if docs are updated or there's a new section, there will be a comment in the same discussion with the link to the new translation to review. |
|||
File diff suppressed because it is too large
Loading…
Reference in new issue