GitHub 搜索 Django REST 框架

为 REST 框架做出贡献

世界只能一次改变一部分。艺术在于选择那部分。

— 蒂姆·伯纳斯-李

有很多方法可以为 Django REST 框架做出贡献。我们希望它成为一个社区主导的项目，因此请参与进来，帮助塑造项目的未来。

注意：在它的生命周期中，我们认为 Django REST 框架在本质上是功能完备的。我们可能会接受跟踪 Django 版本持续开发的拉取请求，但更希望不接受新功能或代码格式更改。

社区

你可以为推动 REST 框架项目向前发展做出的最重要的事情就是尽可能积极地参与。代码贡献通常被高估为参与项目的首要方式，我们不认为需要如此。

如果你使用 REST 框架，我们希望你能够大声说出你的使用体验——你可以考虑撰写一篇关于使用 REST 框架的博客文章，或发布一篇关于使用特定 JavaScript 框架构建项目的教程。初学者的经验可能特别有帮助，因为你将能够最好地评估 REST 框架的哪些部分更难理解和使用。

你可以帮助社区向前发展的一些其他非常好的方法包括帮助回答 讨论组 中的问题，或在 StackOverflow 上设置 电子邮件提醒，以便在带有 django-rest-framework 标签的任何新问题出现时收到通知。

在回答问题时，请务必通过超链接到相关的主题和工单（只要有可能），帮助未来的贡献者找到解决方法，并在相关时包含来自这些项目的反向链接。

行为准则

请保持礼貌和专业的语气。对于某些用户来说，在 REST 框架邮件列表或工单跟踪器上的讨论可能是他们第一次与开源社区接触。第一印象很重要，所以让我们尝试让每个人都感到受欢迎。

注意您选择的语言。例如，在男性占主导地位的环境中，以“嗨，伙计们”开头的帖子可能会无意中产生排他性。在这些情况下，使用性别中立的语言同样容易，而且更具包容性。

Django 行为准则 为参与社区论坛提供了更全面的指南。

问题

我们的贡献流程是，GitHub 讨论页面 通常应该是您的起点。如果您在讨论后被推荐这样做，请仅提出问题或拉取请求。

关于良好潜在问题报告的一些提示

  • 在描述问题时，请尝试根据您认为需要更改的行为来表述您的工单，而不是您认为需要更改的代码。
  • 在 GitHub 项目页面中搜索相关项目，并在报告问题之前确保您运行的是 REST 框架的最新版本。
  • 功能请求通常会关闭，并建议在核心 REST 框架库之外实现这些请求。将新功能请求保持为第三方库实现，使我们能够降低 REST 框架的维护开销，以便专注于持续的稳定性、错误修复和出色的文档。在其生命周期的这一点上，我们认为 Django REST 框架在本质上是功能完备的。
  • 关闭问题并不一定意味着讨论的结束。如果您认为您的问题被错误地关闭，请解释原因，我们将考虑是否需要重新打开它。

问题分类

参与筛选传入问题是开始做出贡献的好方法。需要审查进入工单跟踪器的每张工单，以确定下一步应该采取什么措施。任何人都可以提供帮助，您只需要愿意

  • 通读工单 - 它有意义吗？它是否缺少任何有助于更好地解释它的上下文？
  • 工单是否报告在正确的位置？它是否更适合作为讨论组中的讨论？
  • 如果工单是错误报告，您能重现它吗？您能否编写一个失败的测试用例来演示问题，并可以作为拉取请求提交？
  • 如果工单是功能请求，您是否同意它，并且该功能请求是否可以作为第三方包实现？
  • 如果一张工单没有太多活动，并且它解决了您需要解决的问题，那么请在工单上发表评论，并尝试找出让它再次启动所需的条件。

开发

若要开始使用 Django REST 框架进行开发，首先在 GitHub 上从 Django REST 框架仓库 创建一个 Fork。

然后克隆你的 Fork。克隆命令将如下所示，其中 YOUR-USERNAME 是你的 GitHub 用户名

git clone https://github.com/YOUR-USERNAME/django-rest-framework

有关更多帮助，请参阅 GitHub 的 Fork 仓库 指南。

更改应广泛遵循 PEP 8 样式约定，我们建议你设置编辑器以自动指示不符合约定的样式。每次提交时，你都可以使用 pre-commit 钩子检查你的贡献是否符合这些约定，我们也会在 CI 上运行这些钩子。要设置它们，首先确保你已安装 pre-commit 工具，例如

python -m pip install pre-commit

然后运行

pre-commit install

测试

要运行测试，请克隆存储库，然后

# Setup the virtual environment
python3 -m venv env
source env/bin/activate
pip install -e .
pip install -r requirements.txt

# Run the tests
./runtests.py

测试选项

使用更简洁的输出样式运行。

./runtests.py -q

针对给定的测试用例运行测试。

./runtests.py MyTestCase

针对给定的测试方法运行测试。

./runtests.py MyTestCase.test_this_method

针对给定的测试方法运行测试的简短形式。

./runtests.py test_this_method

注意：测试用例和测试方法匹配是模糊的，有时会运行其他包含与给定命令行输入部分字符串匹配的测试。

针对多个环境运行

你还可以使用出色的 tox 测试工具针对所有受支持的 Python 和 Django 版本运行测试。全局安装 tox，然后简单地运行

tox

拉取请求

最好尽早提出拉取请求。拉取请求表示讨论的开始，不一定需要是最终的、完成的提交。

在开始处理拉取请求之前，最好始终创建一个新分支。这意味着你稍后可以切换回处理另一个独立问题，而不会干扰正在进行的拉取请求。

另外，记住，如果你有一个未完成的拉取请求，那么将新提交推送到你的 GitHub 仓库也会自动更新拉取请求。

GitHub 关于处理拉取请求的文档 在此处提供。

在提交拉取请求之前始终运行测试，理想情况下运行 tox 以检查你的修改是否与所有受支持的 Python 和 Django 版本兼容。

提出拉取请求后，查看 GitHub 界面中的构建状态，并确保测试按预期运行。

Build status

上面：构建通知

管理兼容性问题

有时，为了确保你的代码在各种不同的 Django、Python 或第三方库版本上运行，你需要根据环境运行略有不同的代码。任何以这种方式分支的代码都应隔离到 compat.py 模块中，并应提供其余代码库可使用的单个通用接口。

文档

REST 框架的文档基于 Markdown 源文件构建，该文件位于 docs 目录 中。

有很多出色的 Markdown 编辑器，它们让使用文档变得非常容易。适用于 Mac 的 Mou 编辑器 就是一款备受推荐的此类编辑器。

构建文档

要构建文档，请使用 pip install mkdocs 安装 MkDocs，然后运行以下命令。

mkdocs build

这会将文档构建到 site 目录中。

你可以使用 serve 命令构建文档并在浏览器窗口中打开预览。

mkdocs serve

语言风格

文档应采用美式英语。文档的语调非常重要 - 尽可能坚持使用简单、通俗、客观且平衡的风格。

其他一些提示

  • 保持段落适当地简短。
  • 不要使用诸如“e.g.”之类的缩写，而应使用长形式，例如“例如”。

Markdown 风格

在处理文档时，你应遵循一些约定。

1. 标题

标题应使用哈希样式。例如

### Some important topic

不应使用下划线样式。不要这样做：

Some important topic
====================

链接应始终使用引用样式，将引用的超链接保留在文档末尾。

Here is a link to [some other thing][other-thing].

More text...

[other-thing]: http://example.com/other/thing

此样式有助于保持文档源的一致性和可读性。

如果你要超链接到另一个 REST 框架文档，你应使用相对链接，并链接到 .md 后缀。例如

[authentication]: ../api-guide/authentication.md

以这种样式链接意味着你将能够在 Markdown 编辑器中单击超链接以打开引用的文档。当文档构建时，这些链接将转换为 HTML 页面的常规链接。

3. 注释

如果你想引起对注释或警告的注意，请使用一对封闭行，如下所示

---

**Note:** A useful documentation note.

---