贡献

django-import-export 是开源的，因此它的发展（或萎缩）与改进部分得益于社区。以下是一些关于如何帮助该项目的指南。

通过贡献，您同意遵守`行为准则 <https://github.com/django-import-export/django-import-export/blob/main/CODE_OF_CONDUCT.md>`_。

哲学

• django-import-export 采用BSD许可证。所有贡献的代码必须要么

  • 作者的原創作品，以BSD許可貢獻，或...

  • 取自另一个项目的作品，根据BSD兼容许可证发布。

• GPL'd（或类似）作品不符合收录条件。

• django-import-export 的 git main 分支应始终保持稳定、生产就绪并通过所有测试。

问题

请查看 常见问题 部分的 FAQ，看看您的问题是否已有答案。

关于使用的一般问题，我们建议发布到Stack Overflow，使用`django-import-export <https://stackoverflow.com/questions/tagged/django-import-export/>`_标签。请搜索现有答案，看看是否有匹配您问题的。如果没有，发布一个新问题，包括尽可能多的相关细节。更多详情请参阅`how to ask <https://stackoverflow.com/help/how-to-ask/>`_。

有关库内部的问题，请提出一个`issue <https://github.com/django-import-export/django-import-export/issues/>`_并使用'question'工作流程。

• 首先检查是否存在已回答您问题的现有问题。

• 记住要尽可能详细地描述问题，以便及时获得解答。

报告问题/功能的指南

所以你发现了一个错误或有一个很棒的功能想法。以下是您应该采取的步骤，以帮助在django-import-export中添加/修复它：

• 首先，检查是否存在针对该错误/功能的现有`issue <https://github.com/django-import-export/django-import-export/issues/>`_或`pull request <https://github.com/django-import-export/django-import-export/pulls/>`_。

• 如果那里没有，请提交一个问题。理想的报告包括：

  • 问题/建议的描述

  • 如何重现该bug。

  • 如果相关，包括您的版本：

    • Python 解释器

    • Django

    • tablib 版本

    • django-import-export

    • 可选地涉及任何其他依赖项

  • 理想情况下，创建一个包含（失败）测试用例的pull request，展示问题所在。这让我们能够轻松复现并修复问题。

贡献代码指南

如果你准备好冒险并贡献一些代码或文档，请考虑以下事项：

• 搜索现有 issues 和 PRs，查看是否已有类似提案。

• 对于重大更改，我们建议先提出一个question，以便我们可以根据以往经验提供建议或指导。

该过程应如下所示：

• 将项目在GitHub上fork到你自己的账户中。

• 克隆你的django-import-export副本。

• 在git中创建一个新分支并在那里提交你的更改。

• 将你的新分支推送到GitHub。

• 再次确保没有关于该问题的现有issue或pull request。

  • 如果有，并且你认为有更好的修复方法，请记下问题编号并在你的pull request中提到它。

• 创建一个新的拉取请求（基于你的分支），包括问题/功能是什么、你的软件版本以及引用任何相关的问题/拉取请求。

• 我们建议设置您的编辑器以自动指示不符合的样式（参见`Development`_）。

为了被合并到django-import-export中，贡献必须满足以下条件：

• 一个坚实的补丁，它：

  • 是清楚的。

  • 适用于所有支持的Python/Django版本。

  • 遵循代码库的现有风格（主要是PEP-8）。

  • 根据需要包含注释以解释代码为何如此运行

• 一个演示先前缺陷的测试用例，现在包含补丁后通过。

• 如果它添加/更改了公共API，则还必须包含这些更改的文档。

• 必须获得适当许可（见`Philosophy`_）。

• 将你自己添加到 AUTHORS 文件中。

如果你的贡献缺少其中任何一项，核心贡献者将必须在合并到django-import-export proper之前添加这些内容，对于全志愿者团队来说，这可能需要大量时间才能完成。

开发

格式化

• 所有文件应使用black自动格式化工具进行格式化。如果已配置，将通过pre-commit运行。

• 项目仓库包含一个``.editorconfig``文件。我们推荐使用支持EditorConfig的文本编辑器以避免缩进和空格问题。

• 我们允许最多88个字符，因为这是black使用的行长度。当你运行flake8时，这个检查会被包含在内。文档、注释和文档字符串应该限制在79个字符以内，尽管PEP 8建议的是72。

• 安装 pre-commit:

  python -m pip install pre-commit
  

  然后运行:

  pre-commit install
  

• 如果使用 git blame，你可以忽略对代码库做出大规模更改的提交，例如重新格式化。从项目根目录运行此命令:

  git config blame.ignoreRevsFile .git-blame-ignore-revs
  

创建虚拟环境

克隆并检出仓库后，您可以按以下方式安装新的开发环境:

python -m venv django-import-export-venv
source django-import-export-venv/bin/activate
python -m pip install '.[tests]'

运行测试

你可以运行测试套件使用:

make clean test

构建文档

构建文档的本地版本:

python -m pip install -r requirements/docs.txt
make build-html-doc

文档将出现在 docs/_build/html/index.html 中。