开发人员概述

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

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

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

      git clone git@github.com:your-username/networkx.git
      
    • 添加上游存储库:

      git remote add upstream git@github.com:networkx/networkx.git
      
    • 现在,您的远程存储库名为:

      • upstream ,指的是 networkx 知识库

      • origin 指的是你的个人叉子

  2. 发展你的贡献:

    • 从上游提取最新更改:

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

      git checkout -b bugfix-for-issue-1480
      
    • 随着进度在本地提交 (git addgit commit

  3. 提交您的贡献:

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

      git push origin bugfix-for-issue-1480
      
    • 去GITHUB。新的分支将显示一个绿色的请求按钮---点击它。

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

有关更详细的讨论,请阅读以下内容 detailed documents 关于如何使用Git networkx (https://networkx.github.io/documentation/latest/developer/gitwash/index.html) .

  1. 审查过程:

    • 审阅者(其他开发人员和感兴趣的社区成员)将对您的请求(pull request,PR)编写内联和/或一般性评论,以帮助您改进其实现、文档和样式。每一个开发人员都会对他们的代码进行审查,我们会发现这是一个友好的对话,从中我们都可以了解到代码质量的整体好处。因此,请不要让审查阻碍你的贡献:它的唯一目的是提高项目的质量,而不是批评(毕竟,我们非常感谢你的捐赠时间!).

    • 要更新拉请求,请在本地存储库中进行更改并提交。一旦将这些更改向上推(推到与以前相同的分支),拉请求将自动更新。

    • Travis-CI _这是一个持续集成服务,在每次请求更新后都会触发,以构建代码并运行分支的单元测试。Travis测试必须通过才能合并您的PR。如果Travis失败,您可以通过单击“失败”图标(红十字会)并检查构建和测试日志来找出原因。

    • AppVeyor _是我们使用的另一个持续集成服务。您还需要确保Appveyor测试通过。

注解

如果关闭bug,还应添加“修复1480”,其中1480是问题编号。

之间的分歧 upstream master 你的特色分支

不要把主分支合并到你的分支中。如果Github指示拉请求的分支不能再自动合并,请重新设置为master::

git checkout master
git pull upstream master
git checkout bugfix-for-issue-1480
git rebase master

如果发生任何冲突,请修复相应的文件并继续:

git add conflict-file1 conflict-file2
git rebase --continue

但是,您应该只对自己的分支进行重新设置,并且通常不能对与其他人协作的任何分支进行重新设置。

最后,你必须推动你的再平衡分支:

git push --force origin bugfix-for-issue-1480

(如果您好奇,下面将进一步讨论 dangers of rebasing . 也看到这个 LWN article

生成环境设置

一旦克隆了networkx存储库的fork,就应该为networkx定制一个python开发环境。您可以选择自己选择的环境管理器。在这里,我们为两位受欢迎的环境管理者提供指导: venv (基于PIP)和 conda (水蟒或小水蟒)。

静脉注射

使用时 venv ,您可能会发现以下bash命令很有用:

# 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 all development and runtime dependencies of networkx
pip install -r <(cat requirements/*.txt)
# Build and install networkx from source
pip install -e .
# Test your installation
PYTHONPATH=. pytest networkx

康达

使用conda时,您可能会发现以下bash命令很有用:

# Create a conda environment named ``networkx-dev``
conda create --name networkx-dev
# Activate it
conda activate networkx-dev
# Install major development and runtime dependencies of networkx
# (the rest can be installed from conda-forge or pip, if needed)
conda install `for i in requirements/{default,test,doc,extras}.txt; do echo -n " --file $i "; done`
# Install minimal testing dependencies
conda install pytest
# Install networkx from source
pip install -e . --no-deps
# Test your installation
PYTHONPATH=. pytest networkx

指南

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

  • 所有代码都应记录在案 standard 像麻木和坐骨神经痛一样。

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

文体指南

  • 设置编辑器以删除尾随空格。跟随 PEP08 . 检查代码 pyflakes / flake8 .

  • 使用以下导入约定:

    import numpy as np
    import scipy as sp
    import matplotlib as mpl
    import matplotlib.pyplot as plt
    import networkx as nx
    
    cimport numpy as cnp # in Cython code
    

测试

networkx 具有广泛的测试套件,可确保在系统上正确执行。在合并pull请求之前,测试套件必须通过,并且应该添加测试以覆盖对代码基的任何修改。

我们利用 pytest 测试框架,测试位于 networkx/submodule/tests 文件夹。

使用 pytest ,请确保以开发模式安装库:

$ pip install -e .

现在,使用以下命令运行所有测试:

$ 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%。

要测量测试覆盖率,请安装 pytest-cov (使用) pip install pytest-cov )然后跑:

$ 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%
...

提取请求代码

当您向GitHub提交请求时,GitHub将要求您提供摘要。如果您的代码尚未准备好合并,但您希望获得反馈,请考虑使用 WIP: experimental optimization 或类似于您请求的标题。这样,我们都知道它还没有准备好合并,您可能对设计的更基本的评论感兴趣。

当您认为请求已准备好合并时,请更改标题(使用 Edit 按钮)删除 WIP: .

开发者笔记

有关为NetworkX做出贡献的其他信息,请参阅 Developer Notes .

漏洞

拜托 report bugs on GitHub .