参与者指南#

备注

本文档假定您对使用GitHub Pull请求为开源科学Python项目做出贡献有一定的了解。如果这不能描述您，您可能首先想要查看 新建贡献者常见问题解答 。

开发工作流程#

  1. 如果你是第一次投稿人：

    • 去 https://github.com/networkx/networkx 然后单击“fork”按钮创建您自己的项目副本。

    • 将项目克隆到本地计算机：

      git clone git@github.com:your-username/networkx.git

    • 导航到文件夹networkx并添加上游存储库：

      git remote add upstream git@github.com:networkx/networkx.git

    • 现在，您的远程存储库名为：

      • upstream ，指的是 networkx 知识库

      • origin 指的是你的个人叉子

    • 接下来，您需要设置构建环境。以下是两个流行的环境管理器的说明：

      • venv （基于pip）

        # Create a virtualenv named ``networkx-dev`` that lives in the directory of
# the same name
python -m venv networkx-dev
# Activate it
source networkx-dev/bin/activate
# Install main development and runtime dependencies of networkx
pip install -r requirements/default.txt -r requirements/test.txt -r requirements/developer.txt
#
# (Optional) Install pygraphviz, pydot, and gdal packages
# These packages require that you have your system properly configured
# and what that involves differs on various systems.
# pip install -r requirements/extra.txt
#
# Build and install networkx from source
pip install -e .
# Test your installation
PYTHONPATH=. pytest networkx

      • conda （ Python 或小型 Python ）

        # Create a conda environment named ``networkx-dev``
conda create --name networkx-dev
# Activate it
conda activate networkx-dev
# Install main development and runtime dependencies of networkx
conda install -c conda-forge --file requirements/default.txt --file requirements/test.txt --file requirements/developer.txt
#
# (Optional) Install pygraphviz, pydot, and gdal packages
# These packages require that you have your system properly configured
# and what that involves differs on various systems.
# conda install -c conda-forge --file requirements/extra.txt
#
# Install networkx from source
pip install -e .
# Test your installation
PYTHONPATH=. pytest networkx

    • 最后，我们建议您使用pre-commit钩子，当您键入时，它将以黑色显示 git commit ：：

      pre-commit install

  2. 发展你的贡献：

    • 从上游提取最新更改：

      git checkout main
git pull upstream main

    • 为要处理的功能创建分支。由于分支名称将出现在合并消息中，请使用合理的名称，如“bugfix-for-issue-1480”：：

      git checkout -b bugfix-for-issue-1480

    • 随着进度在本地提交 (git add 和 git commit ）

  3. 测试你的贡献：

    • 在本地运行测试套件（请参阅 Testing 详情）：：

      PYTHONPATH=. pytest networkx

    • 在本地运行测试 之前 提交拉请求有助于尽早发现问题，并减少持续集成系统的负载。

  4. 提交您的贡献：

    • 将更改推回到Github上的fork:：

      git push origin bugfix-for-issue-1480

    • 去GITHUB。新的分支将显示一个绿色的请求按钮---点击它。

    • 如果你想，可以贴在 mailing list 解释你的变化或要求审查。

  5. 审查过程：

    • 每次拉入请求(PR)更新都会触发一组 continuous integration 检查代码是否符合标准并通过我们所有测试的服务。这些检查必须通过，然后才能合并您的公关。如果其中一个检查失败，您可以通过单击“失败”图标(红十字)并检查构建和测试日志来找出原因。

    • 审查者(其他开发人员和感兴趣的社区成员)将在您的公关上写内联和/或一般性评论，以帮助您改进其实现、文档和风格。在这个项目中工作的每个开发人员都会对他们的代码进行审查，我们已经将其视为友好的对话，我们都从中学到了东西，并从中获得了整体代码质量的好处。因此，请不要让审查打击您的贡献：它的唯一目的是提高项目质量，而不是批评(毕竟，我们非常感谢您捐赠的时间！)

    • 要更新您的PR，请在您的本地存储库上进行更改并提交。一旦这些更改被推送到(与以前相同的分支)，PR将自动更新。

    备注

    如果PR关闭了一个问题，请确保GitHub知道在合并PR时自动关闭问题。例如，如果PR关闭了1480号问题，则可以在PR描述或提交消息中使用短语“Fixes#1480”。

  6. 文件更改

    如果您的更改引入了任何API修改，请更新 doc/release/release_dev.rst .

    要将函数设置为弃用，请执行以下操作：

    • 使用弃用警告来警告用户。例如：：

      msg = "curly_hair is deprecated and will be removed in v3.0. Use sum() instead."
warnings.warn(msg, DeprecationWarning)

    • 向…添加警告 networkx/conftest.py ：：

      warnings.filterwarnings(
    "ignore", category=DeprecationWarning, message=<start of message>
)

    • 向…添加提醒 doc/developer/deprecations.rst 以便团队将来删除不推荐使用的功能。例如：

      * In ``utils/misc.py`` remove ``generate_unique_node`` and related tests.

    • 向添加备注(以及指向公关的链接) doc/release/release_dev.rst ：

      [`#4281 <https://github.com/networkx/networkx/pull/4281>`_]
Deprecate ``read_yaml`` and ``write_yaml``.

    备注

    对于审阅者：确保合并消息中包含对更改的简要描述，如果PR关闭了问题，则添加“closes#123”，其中123是问题编号。

与…不同 upstream main#

如果GitHub指示您的Pull请求的分支不能再自动合并，请将主分支合并到您的分支中：：

git fetch upstream main
git merge upstream/main

如果发生任何冲突，则需要在继续之前修复这些冲突。使用以下命令查看冲突的文件：

git status

显示一条消息，如：

Unmerged paths:
  (use "git add <file>..." to mark resolution)

  both modified:   file_with_conflict.txt

在冲突的文件中，您会发现如下部分：

<<<<<<< HEAD
The way the text looks in your branch
=======
The way the text looks in the main branch
>>>>>>> main

选择应保留的文本的一个版本，然后删除其余版本：

The way the text looks in your branch

现在，添加固定文件：

git add file_with_conflict.txt

一旦修复了所有合并冲突，请执行以下操作：

git commit

备注

高级Git用户可能想要改变基数而不是合并，但我们会以任何一种方式挤压和合并PR。

指南#

  • 所有代码都应该进行测试。

  • 所有代码都应按相同的方式进行文档记录 standard 作为NumPy和SciPy。

  • 审查所有变更。询问 mailing list 如果你没有收到你的请求。

  • 中列出了默认依赖项 requirements/default.txt 和额外的（即可选的）依赖项在中列出 requirements/extra.txt . 我们不经常添加新的默认值和额外的依赖项。如果您正在考虑添加具有依赖关系的代码，则应首先考虑添加一个库示例。通常，新提出的依赖项将首先作为额外的依赖项添加。额外的依赖项应该很容易安装在所有平台上并得到广泛应用。新的默认依赖项应该易于在所有平台上安装，在社区中广泛使用，并且已经证明了在NetworkX中广泛使用的潜力。

  • 使用以下导入约定：

    import numpy as np
import scipy as sp
import matplotlib as mpl
import matplotlib.pyplot as plt
import pandas as pd
import networkx as nx

    导入后 sp 用于 ``scipy` ：：

    import scipy as sp

    使用以下导入：

    import scipy.linalg  # call as sp.linalg
import scipy.sparse  # call as sp.sparse
import scipy.sparse.linalg  # call as sp.sparse.linalg
import scipy.stats  # call as sp.stats
import scipy.optimize  # call as sp.optimize

    例如，许多库都有一个 linalg 子包： nx.linalg ， np.linalg ， sp.linalg ， sp.sparse.linalg 。上面的导入模式使任何特定实例的 linalg 明确地说。

  • 使用装饰器 not_implemented_for 在里面 networkx/utils/decorators.py 指定函数不接受“有向”、“无向”、“多图”或“图”。修饰函数的第一个参数应该是要检查的图形对象。

    @nx.not_implemented_for("directed", "multigraph")
def function_not_for_MultiDiGraph(G, others):
    # function not for graphs that are directed *and* multigraph
    pass


@nx.not_implemented_for("directed")
@nx.not_implemented_for("multigraph")
def function_only_for_Graph(G, others):
    # function not for directed graphs *or* for multigraphs
    pass

测试#

networkx has an extensive test suite that ensures correct execution on your system. The test suite has to pass before a pull request can be merged, and tests should be added to cover any modifications to the code base. We make use of the pytest 测试框架，测试位于 networkx/submodule/tests 文件夹。

要运行所有测试：

$ PYTHONPATH=. pytest networkx

或特定子模块的测试：

$ PYTHONPATH=. pytest networkx/readwrite

或来自特定文件的测试：

$ PYTHONPATH=. pytest networkx/readwrite/tests/test_yaml.py

或者文件中的一个测试：

$ PYTHONPATH=. pytest networkx/readwrite/tests/test_yaml.py::TestYaml::testUndirected

使用 --doctest-modules 去做医生。例如，使用以下命令运行所有测试和所有doctest：

$ PYTHONPATH=. pytest --doctest-modules networkx

理想情况下，模块的测试应该覆盖该模块中的所有代码，即语句覆盖率应该为100%。

要测量测试覆盖率，请运行：

$ PYTHONPATH=. pytest --cov=networkx networkx

这将为中的每个文件打印一行报告 networkx ，详细说明测试覆盖范围：

Name                                             Stmts   Miss Branch BrPart  Cover
----------------------------------------------------------------------------------
networkx/__init__.py                                33      2      2      1    91%
networkx/algorithms/__init__.py                    114      0      0      0   100%
networkx/algorithms/approximation/__init__.py       12      0      0      0   100%
networkx/algorithms/approximation/clique.py         42      1     18      1    97%
...

添加测试#

如果你. 测试新手 有关要执行的操作的示例，请参阅现有的测试文件。 不要让考试妨碍了你提交你的投稿！ 如果你不确定该怎么做，或者遇到了麻烦，无论如何都要提交你的拉请求。我们将帮助您创建测试，并在代码审查期间找出任何类型的问题。

添加示例#

图库示例由管理 sphinx-gallery 。示例库的源文件是 .py 中的脚本 examples/ 会产生一个或多个数字。它们是在构建文档时由sphinx-Gallery自动执行的。输出被收集并组装到图库中。

你可以的 添加新的 通过放置新的 .py 目录中的一个目录中的 examples 存储库的目录。请参阅其他示例以了解该格式的概念。

备注

图库示例应以 plot_ ，例如 plot_new_example.py

制作一个好的画廊情节的一般指导原则：

  • 示例应突出显示单个功能/命令。

  • 试着让这个例子尽可能简单。

  • 示例所需的数据应该包含在相同的目录和示例脚本中。

  • 添加注释以解释阅读代码后不明显的情况。

  • 描述您正在展示的功能，并链接到文档的其他相关部分。

添加引用#

如果您正在贡献一种新的算法(或对当前算法的改进)，也应该在函数文档字符串中提供参考论文或资源。有关已发表的论文的参考资料，我们尽量遵循 Chicago Citation Style 。以这种风格生成引文的最快方法是搜索 Google Scholar 并点击 cite 纽扣。它将弹出多种格式的论文引文，并复制 Chicago 风格。

我们更喜欢为URL添加DOI链接。如果DOI链接解析为文章的付费版本，我们更愿意添加指向arxiv版本(如果可用)或任何其他可公开访问的论文副本的链接。

引用的示例：：

.. [1] Cheong, Se-Hang, and Yain-Whar Si. "Force-directed algorithms for schematic drawings and
placement: A survey." Information Visualization 19, no. 1 (2020): 65-91.
https://doi.org/10.1177%2F1473871618821740

如果资源以PDF/DOCX/PPT格式上传到网络(课堂讲稿、演示文稿)，最好使用 wayback machine 创建资源的快照并链接Internet档案链接。资源的URL可以更改，并且它会创建文档中无法访问的链接。

图像对比#

要运行映像比较，请执行以下操作：

$ PYTHONPATH=. pytest --mpl --pyargs networkx.drawing

这个 --mpl 诉说 pytest 要使用 pytest-mpl 将生成的曲线图与中存储的基线曲线图进行比较 networkx/drawing/tests/baseline 。

要添加新测试，请将测试函数添加到 networkx/drawing/tests 这将返回一个Matplotlib Figure(或任何具有savefig方法的Figure对象)，并按如下方式进行修饰：

@pytest.mark.mpl_image_compare
def test_barbell():
    fig = plt.figure()
    barbell = nx.barbell_graph(4, 6)
    # make sure to fix any randomness
    pos = nx.spring_layout(barbell, seed=42)
    nx.draw(barbell, pos=pos)
    return fig

然后创建基准图像以供稍后进行比较：：

$ pytest -k test_barbell --mpl-generate-path=networkx/drawing/tests/baseline

和测试：

$ pytest -k test_barbell --mpl

漏洞#

拜托 report bugs on GitHub .

政策#

与项目的所有交互均受 NetworkX code of conduct 。

我们还遵循以下政策：