有兴趣回馈社区吗？也许您在Django中发现了一个您希望修复的错误，或者您想添加一个小功能（但请记住，新功能的提案应该遵循 process for suggesting new features ).
向Django本身做出贡献是解决您自己担忧的最佳方式。乍一看，这似乎令人畏惧，但这是一条经过广泛探索的道路，有文档、工具和社区来支持您。我们将引导您完成整个过程，以便您可以通过例子学习。
参见
如果您正在寻找有关编写代码的详细信息的参考资料，请参阅 贡献代码 文件。
在本教程中，我们希望您至少对Django的工作方式有基本的了解。这意味着您应该能够轻松地阅读现有的教程 writing your first Django app .此外，您应该对Python本身有很好的了解。但如果你不这样做， Dive Into Python 对于初学Python程序员来说，是一本非常棒的（免费的）在线书籍。
那些不熟悉版本控制系统和Trac的人会发现本教程及其链接包含的信息刚好足以入门。然而，如果您计划定期为Django做出贡献，您可能会想要阅读有关这些不同工具的更多信息。
不过，在大多数情况下，本教程试图尽可能多地解释，以便对最广泛的受众有用。
从哪里获得帮助：
如果您在阅读本教程时遇到困难，请在 Django Forum 或顺便拜访 Django Discord server 与其他可能能够提供帮助的Django用户聊天。
我们将带领您第一次为Django做出贡献。在本教程结束时，您应该对所涉及的工具和流程有了基本的了解。具体来说，我们将涵盖以下内容：
安装Git。
下载Django开发版本的副本。
运行Django的测试套件。
为您的更改编写测试。
为您的更改编写代码。
测试您的更改。
提交拉取请求。
在哪里查找更多信息。
完成教程后，您可以查看其余部分 Django's documentation on contributing .它包含了很多重要的信息，是任何想成为Django定期贡献者的人的必读读物。如果您有问题，它可能已经有答案了。
需要Python 3！
Django的当前版本不支持Python 2.7。获取Python 3 Python's download page 或使用操作系统的包管理器。
对于Windows用户
看见 安装Python 在Windows文档上获取更多指导。
作为贡献者，您可以帮助我们保持Django社区的开放性和包容性。请阅读并关注我们的 Code of Conduct 。
对于本教程，您需要安装Git才能下载Django的当前开发版本并为您所做的更改生成分支。
要检查您是否安装了Git，请输入 git into the command line. If you get messages saying that this command could not be found, you'll have to download and install it, see Git's download page.
如果您对Git不是那么熟悉，您随时可以通过输入以下内容来了解有关其命令的更多信息（一旦安装完毕） git help 进入命令行。
为Django做出贡献的第一步是获取源代码的副本。首先， fork Django on GitHub .然后，从命令行中使用 cd 命令导航到您希望本地Django副本所在的目录。
使用以下命令下载Django源代码存储库：
$ git clone https://github.com/YourGitHubName/django.git
...\> git clone https://github.com/YourGitHubName/django.git
低带宽连接？
您可以添加 --depth 1 参数为 git clone 跳过下载Django的所有提交历史记录，这将数据传输从~250 MB减少到~70 MB。
既然您拥有了Django的本地副本，您就可以像使用安装任何包一样安装它 pip .最方便的方法是使用 virtual environment ，这是Python内置的一项功能，允许您为每个项目保留单独的已安装包目录，以便它们不会相互干扰。
将所有虚拟环境保存在一个地方是个好主意，例如 .virtualenvs/ 在您的主目录中。
通过运行以下操作创建新的虚拟环境：
$ python3 -m venv ~/.virtualenvs/djangodev
...\> py -m venv %HOMEPATH%\.virtualenvs\djangodev
该路径是新环境将保存在您的计算机上的位置。
设置虚拟环境的最后一步是激活它：
$ source ~/.virtualenvs/djangodev/bin/activate
如果 source 命令不可用，您可以尝试使用点：
$ . ~/.virtualenvs/djangodev/bin/activate
每当打开新的终端窗口时，您都必须激活虚拟环境。
对于Windows用户
要在Windows上激活虚拟环境，请运行：
...\> %HOMEPATH%\.virtualenvs\djangodev\Scripts\activate.bat
当前激活的虚拟环境的名称显示在命令行上，以帮助您跟踪正在使用的虚拟环境。您安装的任何内容 pip 显示此名称时，将安装在该虚拟环境中，与其他环境和系统范围的包隔离。
继续安装之前克隆的Django副本：
$ python -m pip install -e /path/to/your/local/clone/django/
...\> py -m pip install -e \path\to\your\local\clone\django\
已安装的Django版本现在通过以可编辑模式安装来指向您的本地副本。您将立即看到您对它所做的任何更改，这在撰写您的第一篇文章时非常有帮助。
使用Django项目测试您的本地更改可能很有帮助。首先，你必须创建一个新的虚拟环境， install the previously cloned local copy of Django in editable mode ，并在本地Django副本之外创建一个新的Django项目。您将立即看到您在新项目中对Django所做的任何更改，这在撰写您的第一篇文章时非常有帮助，尤其是在测试UI的任何更改时。
您可以按照 tutorial 获取有关创建Django项目的帮助。
当为Django做出贡献时，非常重要的是您的代码更改不会将错误引入Django的其他区域。检查Django在您做出更改后仍然可以工作的一种方法是运行Django的测试套件。如果所有测试仍然通过，那么您可以合理地确定您的更改有效并且没有破坏Django的其他部分。如果您以前从未运行过Django的测试套件，那么最好提前运行一次它以熟悉其输出。
在运行测试套件之前，进入Django tests/ 目录中使用 cd tests 命令，并通过运行以下命令安装测试依赖项：
$ python -m pip install -r requirements/py3.txt
...\> py -m pip install -r requirements\py3.txt
如果在安装过程中遇到错误，您的系统可能缺少一个或多个Python包的依赖项。请参考失败包的文档或使用您遇到的错误消息在Web上搜索。
现在我们已经准备好运行测试套件了：
$ ./runtests.py
...\> runtests.py
现在坐下来放松一下。Django的整个测试套件有数千个测试，运行至少需要几分钟时间，具体取决于您计算机的速度。
当Django的测试套件运行时，您会看到代表每个测试完成时状态的字符流。 E 指示测试期间出现错误，并且 F 表明测试的断言失败。这两者都被认为是测试失败。与此同时 x 和 s 分别指示预期失败和跳过的测试。点表示通过测试。
跳过测试通常是由于缺少运行测试所需的外部库;请参阅 运行所有测试 获取依赖项列表，并确保安装任何与您正在进行的更改相关的测试（本教程不需要任何依赖项）。某些测试特定于特定的数据库后台，如果不使用该后台进行测试，则会跳过。SQLite是默认设置的数据库后台。要使用不同的后台运行测试，请参阅 使用另一个 settings 模块 。
测试完成后，您应该会看到一条消息，通知您测试套件是否通过了。由于您尚未对Django的代码进行任何更改，因此整个测试套件 should 过去的如果您遇到失败或错误，请确保您正确遵循了之前的所有步骤。看到 运行单元测试 以获取更多信息。
请注意，最新的Django主分支可能并不总是稳定的。当针对“main”进行开发时，您可以检查 Django's continuous integration builds 以确定这些故障是否特定于您的计算机，或者它们是否也出现在Django的官方版本中。如果您点击查看特定的构建，您可以查看“配置矩阵”，其中显示了按Python版本和数据库后端细分的故障。
备注
对于本教程和我们正在开发的Ticket，针对SQLite进行测试就足够了，但是，有可能(有时也是必要的) run the tests using a different database 。更改用户界面时，您需要 run the Selenium tests 。
在本教程中，我们将以“假已接受门票”作为案例研究。以下是想象中的细节：
门票#99999 --允许做吐司
Django应该提供一个功能 django.shortcuts.make_toast() 返回 'toast' 。
我们现在将实现此功能和相关测试。
在进行任何更改之前，请为票证创建一个新分支：
$ git checkout -b ticket_99999
...\> git checkout -b ticket_99999
您可以选择任何想要的分支名称，“ticket_99999”就是一个例子。此分支中所做的所有更改都将特定于票据，不会影响我们之前克隆的代码的主副本。
在大多数情况下，要想让Django接受贡献，就必须包括测试。对于错误修复贡献，这意味着编写一个回归测试，以确保该错误以后不会重新引入Django。回归测试的编写方式应该是，在错误仍然存在时它会失败，并在错误修复后通过。对于包含新功能的贡献，您需要包括确保新功能正确工作的测试。当新功能不存在时，它们也应该失败，然后在实现后通过。
做到这一点的一个好方法是先编写新测试，然后再对代码进行任何更改。这种开发方式被称为 test-driven development 并且可以应用于整个项目和单个变更。编写测试后，您然后运行它们以确保它们确实失败（因为您还没有修复该错误或添加该功能）。如果您的新测试没有失败，您需要修复它们，以便它们失败。毕竟，无论是否存在错误都通过的回归测试对于防止该错误在未来再次发生并没有太大帮助。
现在来看看我们的实际例子。
为了解析此票证，我们将添加一个 make_toast() 函数添加到 django.shortcuts 模块。首先，我们将编写一个测试，尝试使用该函数并检查其输出是否正确。
导航到Django ' s tests/shortcuts/ 文件夹并创建新文件 test_make_toast.py .添加以下代码：：
from django.shortcuts import make_toast
from django.test import SimpleTestCase
class MakeToastTests(SimpleTestCase):
def test_make_toast(self):
self.assertEqual(make_toast(), "toast")
此测试检查 make_toast() 退货 'toast' 。
但这个测试看起来有点难……
如果您以前从未处理过测试，那么乍一看它们可能会显得有点难以写。幸运的是，测试是 very 这是计算机编程中的一个大学科，所以有很多信息：
关于Django编写测试的初步了解可以在 编写和运行测试 。
《潜入Python》（一本适合初学Python开发人员的免费在线书籍）包括一本很棒的 introduction to Unit Testing.
读完这些之后，如果你想要一些更肉的东西来深入研究，那就有 Python 了 unittest 文件。
由于我们没有对 django.shortcuts 然而，我们的测试应该失败。让我们在中运行所有测试 shortcuts 文件夹以确保确实发生了这样的情况。 cd 致姜戈 tests/ 目录并运行：
$ ./runtests.py shortcuts
...\> runtests.py shortcuts
如果测试运行正确，您应该会看到与我们添加的测试方法对应的一个失败，并显示以下错误：
ImportError: cannot import name 'make_toast' from 'django.shortcuts'
如果所有测试均通过，则您需要确保已将上面显示的新测试添加到适当的文件夹和文件名中。
接下来我们将添加 make_toast() 功能。
导航到 django/ 文件夹并打开 shortcuts.py 文件.在底部添加：：
def make_toast():
return "toast"
现在我们需要确保我们之前编写的测试通过，以便我们可以查看我们添加的代码是否正确工作。再次，导航到Django tests/ 目录并运行：
$ ./runtests.py shortcuts
...\> runtests.py shortcuts
一切都应该过去。如果没有，请确保将该函数正确添加到正确的文件中。
一旦您验证您的更改和测试正常工作，最好运行整个Django测试套件，以验证您的更改没有将任何错误引入Django的其他区域。虽然成功通过整个测试套件并不能保证您的代码没有错误，但它确实有助于识别许多可能被忽视的错误和回归。
要运行整个Django测试套件， cd 进入姜戈 tests/ 目录并运行：
$ ./runtests.py
...\> runtests.py
这是一项新功能，因此应该对其进行记录。打开文件 docs/topics/http/shortcuts.txt 并在文件末尾添加以下内容：
``make_toast()``
================
.. function:: make_toast()
.. versionadded:: 2.2
Returns ``'toast'``.
由于这一新功能将在即将发布的版本中出现，因此它也被添加到Django的下一个版本的发行说明中。在中打开最新版本的发行说明 docs/releases/ ，在撰写本文时，它是 2.2.txt 。在“次要特征”标题下添加注释：
:mod:`django.shortcuts`
~~~~~~~~~~~~~~~~~~~~~~~
* The new :func:`django.shortcuts.make_toast` function returns ``'toast'``.
有关编写文档的更多信息，包括解释 versionadded 位就是全部，看到了 编写文档 .该页面还包括如何在本地构建文档副本的说明，以便您可以预览将生成的HTML。
现在是时候审查分支中所做的更改了。要准备好提交所有更改，请运行：
$ git add --all
...\> git add --all
然后显示Django的当前副本（包含您的更改）与您最初在本教程中使用的版本之间的差异：
$ git diff --cached
...\> git diff --cached
使用箭头键上下移动。
diff --git a/django/shortcuts.py b/django/shortcuts.py
index 7ab1df0e9d..8dde9e28d9 100644
--- a/django/shortcuts.py
+++ b/django/shortcuts.py
@@ -156,3 +156,7 @@ def resolve_url(to, *args, **kwargs):
# Finally, fall back and assume it's a URL
return to
+
+
+def make_toast():
+ return 'toast'
diff --git a/docs/releases/2.2.txt b/docs/releases/2.2.txt
index 7d85d30c4a..81518187b3 100644
--- a/docs/releases/2.2.txt
+++ b/docs/releases/2.2.txt
@@ -40,6 +40,11 @@ database constraints. Constraints are added to models using the
Minor features
--------------
+:mod:`django.shortcuts`
+~~~~~~~~~~~~~~~~~~~~~~~
+
+* The new :func:`django.shortcuts.make_toast` function returns ``'toast'``.
+
:mod:`django.contrib.admin`
~~~~~~~~~~~~~~~~~~~~~~~~~~~
diff --git a/docs/topics/http/shortcuts.txt b/docs/topics/http/shortcuts.txt
index 7b3a3a2c00..711bf6bb6d 100644
--- a/docs/topics/http/shortcuts.txt
+++ b/docs/topics/http/shortcuts.txt
@@ -271,3 +271,12 @@ This example is equivalent to::
my_objects = list(MyModel.objects.filter(published=True))
if not my_objects:
raise Http404("No MyModel matches the given query.")
+
+``make_toast()``
+================
+
+.. function:: make_toast()
+
+.. versionadded:: 2.2
+
+Returns ``'toast'``.
diff --git a/tests/shortcuts/test_make_toast.py b/tests/shortcuts/test_make_toast.py
new file mode 100644
index 0000000000..6f4c627b6e
--- /dev/null
+++ b/tests/shortcuts/test_make_toast.py
@@ -0,0 +1,7 @@
+from django.shortcuts import make_toast
+from django.test import SimpleTestCase
+
+
+class MakeToastTests(SimpleTestCase):
+ def test_make_toast(self):
+ self.assertEqual(make_toast(), 'toast')
预览完更改后，点击 q 键返回命令行。如果差异看起来可以，那么是时候提交更改了。
要提交更改：
$ git commit
...\> git commit
这将打开文本编辑器来输入提交消息。遵循 commit message guidelines 并写一条类似于以下内容的消息：
Fixed #99999 -- Added a shortcut function to make toast.
提交更改后，将其发送到GitHub上的您的分支机构（如果不同，请用您分支机构的名称替换“ticket_99999”）：
$ git push origin ticket_99999
...\> git push origin ticket_99999
您可以通过访问 Django GitHub page .您会在“您最近推出的分支机构”下看到您的分支机构。单击旁边的“比较并拉取请求”。
请不要在本教程中这样做，但在显示更改预览的下一页面上，您可以单击“创建拉取请求”。
恭喜，您已经学会了如何向Django发出拉取请求！您可能需要的更高级技术的详细信息已在 使用Git和Github 。
现在，您可以通过帮助改进Django的代码库来充分利用这些技能。
在您开始为Django做出贡献之前，您可能应该了解更多有关贡献的信息：
您应该确保阅读Django的文档 claiming tickets and submitting pull requests .它涵盖了Trac礼仪、如何为自己领取门票、预期的编码风格（包括代码和文档）以及许多其他重要细节。
第一次贡献者还应该阅读Django的 documentation for first time contributors .对于我们这些刚接触Django的人来说，它有很多很好的建议。
之后，如果您仍然渴望了解有关贡献的更多信息，您可以随时浏览其余内容 Django's documentation on contributing .它包含大量有用的信息，应该是您回答任何问题的第一来源。
一旦您查看了其中的一些信息，您就可以准备好出去寻找一张自己的门票来做出贡献了。特别注意符合“容易取”标准的门票。这些门票本质上通常简单得多，非常适合首次贡献者。一旦您熟悉了对Django的贡献，您就可以开始处理更困难和复杂的门票。
如果您只是想开始（没有人会责怪您！），尝试查看列表 easy tickets without a branch and the easy tickets that have branches which need improvement. 如果您熟悉编写测试，您还可以查看 easy tickets that need tests. 请记住遵循Django文档链接中提到的有关领取门票的指南 claiming tickets and submitting branches 。
门票有分支后，需要第二双眼睛进行审查。提交拉取请求后，通过将票证上的标志设置为“有补丁”、“不需要测试”等来更新票证元数据，以便其他人可以找到它进行审查。贡献并不一定总是意味着从头开始编写代码。审查打开的拉取请求也是一个非常有帮助的贡献。看到 试用票 了解更多细节。
5月 28, 2025