贡献

首先，我们非常感谢您抽出时间阅读本文！这意味着您正在考虑以某种方式改进 djangopackages.org。它当然需要您的帮助。

以下是为 djangopackages.org 后端代码开发做贡献的方法。

设置

在 GitHub 上派生（Fork）

在做任何其他事情之前，在 GitHub 上登录/注册，并从 GitHub 项目派生 Django Packages。

在本地克隆你的派生仓库

如果您已安装 git，现在可以使用以下命令行参数克隆您的 git 仓库，其中 <my-github-name> 是您在 GitHub 上的账户名

git clone [email protected]:<my-github-name>/djangopackages.git

在本地安装 Django Packages

这些说明使用 Docker 在您的计算机上安装 Django Packages。

如果您遇到问题，请参阅故障排除部分。如果这不能解决您的问题，请通过我们的 问题跟踪器报告。

设置工具

您需要通过安装以下工具来确保您的本地环境已准备就绪。

Docker

如果您尚未安装它们，请安装 Docker 和 Compose。

设置选项

有两种设置您的开发环境的选项

1. 标准 - 在您的终端中使用标准 docker compose 命令
2. Just - 在您的终端中使用 just 命令运行器

设置你的开发环境

运行项目所需的所有环境变量和设置都存储在 .env.local.example 文件中。

为了运行项目，您需要运行以下命令

标准Just

cp .env.local.example .env.local

just setup

构建 Docker 容器

现在使用 Docker Compose 构建项目

标准Just

docker compose build

just build

添加 GitHub API 令牌（可选）

获取一个 GitHub API 令牌并将 .env.local 中的 GITHUB_TOKEN 变量设置为此值。GitHub 仓库处理程序使用此令牌获取仓库元数据，并且某些测试需要此令牌。

运行项目

要启动项目，运行

标准Just

docker compose up --detach

just up --detach

然后将浏览器指向 https://:8000 并开始编码！

创建本地 Django 超级用户

现在，您将在本地运行的 Django Packages 版本上为自己创建一个管理员账户

为自己创建一个 Django 超级用户，将 joe 替换为您的用户名/电子邮件

标准Just

docker compose run django python -m manage createsuperuser --username=joe --email=[email protected]

just createsuperuser joe [email protected]

然后登录到管理界面 (/admin/) 并为您的用户创建一个配置文件，填写所有字段的任何数据。

加载示例数据

我们使用一个模拟（Mock）系统在我们的测试中和运行网站的开发版本时创建示例数据。要创建一些开发数据，只需运行

标准Just

docker compose run --rm django python -m manage load_dev_data

just run load_dev_data

重建搜索索引

接下来，我们需要重建和重新计算我们的搜索数据库。

标准Just

docker compose run --rm django python -m manage searchv2_build

just run searchv2_build

虽然搜索 v2 是我们当前的默认搜索算法，但我们正在测试一个实验性的 v3。要使用 v3 引擎重建和重新计算我们的搜索数据库，我们运行

标准Just

docker compose run --rm django python -m manage searchv3_build

just run searchv3_build

格式化工具、代码检查工具及其他杂项

Pre-commit 是一个有助于组织我们的代码检查工具和自动格式化工具的工具。Pre-commit 会在我们的代码被自动提交之前运行，或者我们可以手动运行它。Pre-commit 也会在 GitHub 上的每个拉取请求中自动运行。

要安装 pre-commit 钩子

pip install pre-commit
pre-commit install

要手动运行所有 pre-commit 规则

pre-commit run --all-files

要手动运行某个 pre-commit 规则

pre-commit run ruff

问题！

Django Packages 的未解决功能请求和 bug 列表可以在我们的 GitHub 问题跟踪器上找到。选择一个您认为可以完成的未分配问题，添加评论说明您正在尝试完成它，很快您的 GitHub ID 匹配的个人标签将被分配给该问题。

欢迎提出未描述的问题！

提示

1. 标记为 starter 的问题被认为是项目、Django 甚至 Python 新手的好入门级任务。
2. 标记为 doc 的问题必须只涉及 docs 文件夹中的内容。

设置主题分支并生成拉取请求

虽然在问题中提供有用的代码片段很方便，但作为开发者，提交拉取请求更好。通过提交拉取请求，您对 Django Packages 的贡献将由 GitHub 记录。

在 git 中，最好将每个主题或功能隔离到“主题分支”中。虽然单独的提交允许您控制对代码进行多小的独立更改，但分支是：将一组与一个功能相关的所有提交分组在一起，或者在您可能同时处理多个主题时隔离不同的工作的好方法。

虽然需要一些经验才能正确把握如何拆分提交，但主题分支的范围应限于提交到问题跟踪器的单个 issue。

此外，由于 GitHub 将拉取请求固定并同步到特定分支，因此这是您一次提交多个修复程序的唯一方法。如果您从开发分支提交拉取，则不能对您的开发分支进行任何更多提交，否则这些提交也将添加到拉取中。

要创建主题分支，最简单的方法是使用 git checkout 命令的便捷 -b 参数

git checkout -b fix-broken-thing

Switched to a new branch 'fix-broken-thing'

您应该为您的分支使用一个足够详细的名称，以便清楚它是什么。现在您可以提交您的更改并定期合并上游的 develop，如下所述。

当您准备好生成拉取请求时，无论是为了初步审查，还是为了考虑合并到项目中，您都必须首先将您的本地主题分支推回到 GitHub

git push origin fix-broken-thing

现在当您访问您在 GitHub 上的派生仓库时，您将在“Source”选项卡下看到此分支，其中显示“Switch Branches”。继续从此列表中选择您的主题分支，然后单击“Pull request”按钮。

在这里您可以添加关于您的分支的评论。如果这是对已提交问题的回应，最好在此初始评论中添加指向该问题的链接。仓库管理员将收到您的拉取请求通知，并会对其进行审查（有关最佳实践，请参阅下文）。请注意，如果您发现需要更改的内容，或者为了回应审查者的评论，您可以继续向您的主题分支添加提交（并将其推送到 GitHub）。如果审查者要求更改，您无需关闭拉取请求并在更改后重新发布。只需在本地进行更改，将其推送到 GitHub，然后向拉取请求的讨论部分添加评论即可。

定期将上游更改拉取到你的派生仓库中

Django Packages 正在快速发展。因此，定期将上游 main 分支的更改拉取到您的派生仓库中至关重要。没有什么比投入数日辛勤工作到拉取请求中却因其与 main 分支偏离太远而被拒绝更糟糕的了。

要拉取上游更改

git remote add upstream https://github.com/djangopackages/djangopackages.git
git fetch upstream main

在合并之前，检查日志以确保您确实需要这些更改

git log upstream/main

然后合并您获取的更改

git merge upstream/main

有关更多信息，请参阅 http://help.github.com/fork-a-repo/

如何让你的拉取请求被接受

我们欢迎您的提交。但我们也希望为我们的用户和社区提供稳定的体验。遵循这些规则，您应该会成功！

运行测试！

在您提交拉取请求之前，请通过以下命令运行整个 Django Packages 测试套件

docker compose run django pytest

核心提交者做的第一件事就是运行这个命令。任何未能通过此测试套件的拉取请求都将被拒绝。

如果你添加了代码/视图，你需要添加测试！

我们深刻体会到，没有测试的代码是不可靠的。如果您的拉取请求因缺乏测试而降低了我们的测试覆盖率，它将被拒绝。

目前，我们使用 Django 测试框架（基于 unittest）。

此外，请尽量保持测试的简单性。复杂的测试最终需要自己的测试。我们宁愿看到测试方法之间重复的断言，也不愿看到巧妙的实用方法神奇地确定在特定阶段需要哪些断言。请记住：显式优于隐式。

不要将代码更改与空白清理混淆

如果您在一个文件中更改了两行代码并修正了 200 行空白问题，那么该拉取请求的差异实际上是无法阅读的，并将被拒绝。空白清理需要单独的拉取请求。

将你的拉取请求限制为单个问题

Django Packages 的拉取请求应该尽可能小/原子化。包含大范围更改的拉取请求将被拒绝，并附有要求您隔离拉取请求中特定代码的评论。一些例子：

1. 如果您正在文档中进行拼写更正，请不要修改 settings.py 文件（pydanny 就犯过这个错误）。
2. 添加新的 仓库处理程序不得触及 Package 模型或其方法。
3. 如果您正在添加新视图，请不要“清理”不相关的视图。该清理应放在另一个拉取请求中。
4. 更改文件的权限应放在单独的拉取请求中，并附有明确的理由。

遵循 PEP-8 并保持代码简洁！

记住 Python 之禅

>>> python -c 'import this'

请保持您的代码尽可能清晰和直接。当我们看到超过一两个函数/方法以 _my_special_function 开头或像 __builtins__.object = str 这样的代码时，我们就会开始担心。我们宁愿拒绝您的出色作品并发送简化请求，而不是试图理解它。

此外，像素短缺已结束。我们希望看到

• package 而不是 pkg
• grid 而不是 g
• my_function_that_does_things 而不是 mftdt

在多个浏览器中测试任何 CSS/布局更改

任何 CSS/布局更改都需要在 Mac、Linux 和 Windows 上的 Chrome、Safari、Firefox、IE8 和 IE9 中进行测试。如果在任何这些浏览器上失败，您的拉取请求将被拒绝，并附注说明哪些浏览器不工作。

拉取请求如何被检查、测试和完成

首先我们将代码拉取到本地分支

git checkout -b <branch-name> <submitter-github-name>
git pull git://github.com/<submitter-github-name/djangopackages.git main

然后我们运行测试

python -m manage test --settings=settings.test

最后进行合并并推送到 GitHub

git checkout main
git merge <branch-name>
git push origin main