如何为Science Kit-Image做出贡献

开发开源软件非常有趣！加入我们的行列 scikit-image mailing list 告诉我们你想要解决以下哪些挑战。

• 对于那些刚接触使用Python进行科学编程的人，可以提供指导。

• 如果您正在寻找要实现或修复的内容，您可以浏览 open issues on GitHub 。

• 该产品的技术细节 development process 总结如下。请参阅 gitwash 获取分步教程。

发展过程

以下是它的详细内容和简短内容：

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

   • 去 https://github.com/scikit-image/scikit-image 并点击“fork”按钮创建您自己的项目副本。

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

     git clone https://github.com/your-username/scikit-image.git
     

   • 更改目录：：

     cd scikit-image
     

   • 添加上游存储库：：

     git remote add upstream https://github.com/scikit-image/scikit-image.git
     

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

     • upstream ，它是指 scikit-image 存储库

     • origin ，这指的是你的个人叉子

备注

尽管我们的代码驻留在 github ，我们的数据集存储在 gitlab 并带着 pooch 。新数据必须在GitLab上提交。一旦合并，数据注册表 skimage/data/_registry.py 在GitHub上的主代码库中必须更新。

2. 发展您的贡献：

   • 从上游获取最新更改：：

     git checkout master
     git pull upstream master
     

   • 为要处理的要素创建分支。由于分支机构名称将出现在合并消息中，请使用合理的名称，如‘Transform-Speedups’：：

     git checkout -b transform-speedups
     

   • 在您的进度中进行本地承诺 (git add 和 git commit )

3. 要提交您的贡献，请执行以下操作：

   • 将您的更改推送回GitHub：：

     git push origin transform-speedups
     

   • 输入您的GitHub用户名和密码(重复贡献者或高级用户可以通过以下方式删除此步骤 connecting to GitHub with SSH )。

   • 转到GitHub。新的分支机构将显示一个绿色的Pull Request键--点击它。

   • 如果您愿意，可以在 mailing list 解释您的更改或要求审查。

For a more detailed discussion, read these detailed documents on how to use Git with scikit-image (使用 scikit-image 源代码).

4. 审查流程：

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

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

   • Travis-CI ，一个持续集成服务，在每次请求更新后触发，以构建代码、运行单元测试、测量代码覆盖率并检查分支的编码风格(PEP8)。在您的公关可以合并之前，Travis测试必须通过。如果Travis失败，您可以通过点击“失败”图标(红十字)并检查构建和测试日志来找出原因。

   • 在合并之前，拉入请求必须得到两个核心团队成员的批准。

5. 文档更改

   如果您的更改引入了任何API修改，请更新 doc/source/api_changes.txt 。

   如果您的更改引入了弃用，请将提醒添加到 TODO.txt 以便团队将来删除不推荐使用的功能。

备注

审查者：如果PR描述不明显，请在合并消息中添加一个简短的分支机构所做的说明，如果关闭了一个错误，还应添加“Close#123”，其中123是问题编号。

两国之间的分歧 upstream master 和您的功能分支

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

git fetch upstream master
git merge upstream/master

如果发生任何冲突，则需要先修复它们，然后才能继续。使用以下命令查看哪些文件存在冲突：

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 master branch
>>>>>>> master

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

The way the text looks in your branch

现在，添加固定文件：：

git add file_with_conflict.txt

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

git commit

备注

鼓励高级Git用户 rebase instead of merge ，但无论哪种方式，我们都会挤压和合并大多数PR。

生成环境设置

请参阅 安装SCRICIT-IMAGE 有关开发安装说明，请参阅。

指导方针

• 所有代码都应该有测试(请参见 test coverage 有关更多详细信息，请参见下文)。

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

• 有关新功能，请始终向库中添加示例(请参见 Sphinx-Gallery 有关更多详细信息，请参见下文)。

• 没有两个核心团队成员的审查和批准，任何变更都不会提交。在网上询问 mailing list 如果您的拉取请求没有得到任何响应。 切勿合并您自己的拉取请求。

文体指南

• 设置您的编辑器以删除尾随空格。关注 PEP08 。用PYFILES/FLAKE8检查代码。

• 使用NumPy数据类型而不是字符串 (np.uint8 而不是 "uint8" )。

• 使用以下导入约定：

  import numpy as np
  import matplotlib.pyplot as plt
  from scipy import ndimage as ndi
  
  # only in Cython code
  cimport numpy as cnp
  cnp.import_array()
  

• 记录数组参数时，请使用 image : (M, N) ndarray ，然后参阅 M 和 N 如有必要，在文档字符串中。

• 将数组维度引用为(平面)、行、列，而不是x、y、z。请参见 Coordinate conventions 有关详细信息，请参阅用户指南。

• 函数应支持所有输入图像数据类型。使用实用程序功能，如 img_as_float 以帮助转换为适当的类型。输出格式可以是任何最高效的格式。这允许我们将几个函数串在一个管道中，例如：：

  hough(canny(my_image))
  

• 使用 Py_ssize_t 作为C/C++和Cython代码中所有索引、形状和大小变量的数据类型。

• 使用相对模块导入，即 from .._shared import xyz 而不是 from skimage._shared import xyz 。

• 将Cython代码包装在一个纯Python函数中，该函数定义API。这提高了与代码自检工具的兼容性，这些工具通常不知道Cython代码。

• 对于Cython函数，请尽可能使用以下命令发布GIL with nogil: 。

测试

请参阅安装指南的测试部分。

测试覆盖范围

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

要测量测试覆盖率，请安装 pytest-cov (使用 pip install pytest-cov )，然后运行：

$ make coverage

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

Name                                             Stmts   Exec  Cover   Missing
------------------------------------------------------------------------------
skimage/color/colorconv                             77     77   100%
skimage/filter/__init__                              1      1   100%
...

为您的叉子激活Travis-CI(可选)

Travis-CI检查项目中的所有单元测试，以防止损坏。

在发送Pull请求之前，您可能需要检查Travis-CI是否成功通过了所有测试。要做到这一点，

• 去 Travis-CI 并按照顶部的登录链接

• 去你的 profile page 打开你的SCRKIT-IMAGE叉子

它对应于中的第一步和第二步 Travis-CI documentation (第三步已经在SCRICKIT-IMAGE中完成)。

因此，一旦您将代码推送到您的分支，它将触发Travis-CI，并且当该过程完成时，您将收到一封电子邮件通知。

每次触发Travis时，它还会调用 Codecov 以检查当前的测试超额。

建筑文档

要构建文档，请运行 make 从 doc 目录。 make help 列出所有目标。例如，要构建HTML文档，您可以运行：

make html

然后，所有的HTML文件都将在 scikit-image/doc/build/html/ 。要重新生成完整的干净文档，请运行：

make clean
make html

要求

Sphinx _, Sphinx-Gallery 和LaTeX是构建文档所必需的。

斯芬克斯：

构建文档所需的Sphinx和其他Python包可以使用以下命令安装： scikit-image/requirements/docs.txt 文件。

pip install -r requirements/docs.txt

Sphinx-Gallery:

上述安装命令包括安装 Sphinx-Gallery ，我们使用它来创建 一般示例 。有关语法和用法的完整说明，请参阅Sphinx-Gallery文档。

如果要向图库提供示例或编辑现有示例，请构建文档(请参见上文)并打开Web浏览器以检查您的编辑内容在 scikit-image/doc/build/html/auto_examples/ ：导航到已添加或更改的文件。

添加示例时，还可以访问 scikit-image/doc/build/html/auto_examples/index.html 查看新缩略图在画廊主页上的呈现方式。要更改缩略图，请参阅 this section 狮身人面像画廊的文件。

请注意，图库示例的最大图形宽度应为8英寸。

Laex Ubuntu：

sudo apt-get install -qq texlive texlive-latex-extra dvipng

LaTeX Mac：

安装完整版本 MacTex 安装或安装较小的 BasicTex 并添加 ucs 和 Dvipng 套餐：

sudo tlmgr install ucs dvipng

修复警告

• “未找到引用：R#”文档字符串的第一行中的引用后可能有下划线(例如 [1]_] 。使用此方法查找源文件：$cd doc/Build；grep-rin R#

• “重复引用R#，其他实例在...”“可能存在 [2] 无.class=‘class 3’> [1] 在其中一个文档字符串中

• 请确保使用指向图像的预拼写路径(而不是_图像目录)

自动生成开发文档

这组说明用于创建SCRICKIT-IMAGE/Tools/Deploy-docs.sh

• 转到Github帐户设置->个人访问令牌

• 创建具有访问权限的新令牌 public_repo 和 user:email only

• 安装Travis命令行工具： gem install travis 。在OSX上，你可以通过 brew install ruby 。

• 获取Github生成的令牌并运行 travis encrypt GH_TOKEN=<token> 从SCRICKIT-IMAGE回收站内部

• 将输出粘贴到的Secure：字段中 .travis.yml 。

• 已解密的GH_TOKEN环境变量将可用于Travis脚本

https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line https://docs.travis-ci.com/user/encryption-keys/

弃用周期

如果必须更改库的行为，则必须遵循弃用循环来警告用户。

• 不推荐使用的循环是 not 在以下情况下有必要：

  • 添加新函数，或

  • 将新的关键字参数添加到 end 函数签名的，或者

  • 修正错误行为

• 弃用周期是必要的，因为 任何破坏性的API更改 ，这意味着

  使用相同参数调用的函数在更改后将返回不同结果的更改。这包括：

  • 更改参数或关键字参数的顺序，或者

  • 向函数添加参数或关键字参数，或者

  • 更改函数的名称或子模块，或

  • 更改函数参数的默认值。

通常，我们的政策是在两个版本上设置一个弃用周期。

为了说明起见，我们考虑修改函数签名中的缺省值。在版本N中(因此，下一版本将是N+1)，我们有

def a_function(image, rescale=True):
    out = do_something(image, rescale=rescale)
    return out

那必须改成

def a_function(image, rescale=None):
    if rescale is None:
        warn('The default value of rescale will change '
             'to `False` in version N+3.', stacklevel=2)
        rescale = True
    out = do_something(image, rescale=rescale)
    return out

在版本N+3中

def a_function(image, rescale=False):
    out = do_something(image, rescale=rescale)
    return out

以下是两个版本的弃用周期的流程：

• 在签名中，将默认设置为 None ，并修改文档字符串以指定它的 True 。

• 在函数中， _if_ 重缩放设置为 None ，设置为 True 并警告默认设置将更改为 False 在版本N+3中。

• 在……里面 doc/release/release_dev.rst ，在“弃用”下添加“in” a_function ，即 rescale 参数将默认为 False 在N+3中。“

• 在……里面 TODO.txt ，在与版本N+3相关的部分中创建一项，并写下“在a_Function中将重定标默认为FALSE”。

请注意，两个版本的弃用循环并不是一个严格的规则，在某些情况下，开发人员可以在合理的情况下同意不同的过程(例如，当我们检测不到更改时，或者它涉及移动或删除整个函数)。

Scikit-Image使用警告来突出显示其API中的更改，以便用户可以相应地更新他们的代码。这个 stacklevel argument sets the location in the callstack where the warnings will point. In most cases, it is appropriate to set the stacklevel to 2. When warnings originate from helper routines internal to the scikit-image library, it is may be more appropriate to set the stacklevel to 3. For more information, see the documentation of the warn 函数。

要测试警告是否正确发出，请尝试从IPython控制台调用该函数。它应该指向控制台输入本身，而不是由SCRKIT-IMAGE库中的文件发出。

• Good ： ipython:1: UserWarning: ...

• Bad ： scikit-image/skimage/measure/_structural_similarity.py:155: UserWarning:

臭虫

请 report bugs on GitHub 。

基准

虽然对于大多数Pull请求不是强制性的，但我们要求与性能相关的PR包括一个基准，以便清楚地描述正在针对其进行优化的用例。可以在以下位置找到我们的快照的历史视图 website 。

在本节中，我们将回顾如何设置基准和三个命令 asv dev ， asv run 和 asv continuous 。

必备条件

从安装开始 airspeed velocity 在您的开发环境中。在安装之前，请确保激活您的开发环境，如果使用 venv 您可以使用以下命令安装该要求：

source skimage-dev/bin/activate
pip install asv

如果您使用的是conda，则命令：：

conda activate skimage-dev
conda install asv

是更合适的。安装后，运行命令：：非常有用

asv machine

让空速知道更多关于你的机器的信息。

编写基准测试

要编写基准测试，请在 benchmarks 包含a类和一个类的目录 setup 方法和至少一个前缀为 time_ 。

这个 time_ 方法应该只包含您希望进行基准测试的代码。因此，将准备基准场景的所有内容移到 setup 方法。此函数在调用 time_ 方法及其执行时间没有考虑到基准中。

以 TransformSuite 基准：

import numpy as np
from skimage import transform

class TransformSuite:
    """Benchmark for transform routines in scikit-image."""

    def setup(self):
        self.image = np.zeros((2000, 2000))
        idx = np.arange(500, 1500)
        self.image[idx[::-1], idx] = 255
        self.image[idx, idx] = 255

    def time_hough_line(self):
        result1, result2, result3 = transform.hough_line(self.image)

在这里，映像的创建是在 setup 方法，并且不包括在基准的报告时间中。

还可以对峰值内存使用率等功能进行基准测试。要详细了解的功能，请执行以下操作 asv, please refer to the official airpseed velocity documentation 。

此外，在基准测试旧版本的SCRICKIT-IMAGE时，基准文件需要是可导入的。因此，如果在顶层导入SCRICKIT-IMAGE中的任何内容，则应该这样做：

try:
    from skimage import metrics
except ImportError:
    pass

基准测试本身不需要对缺失的功能进行任何防范，只需要顶级导入。

为了允许较新函数的测试被标记为“n/a”(不可用)，而不是旧版本的“失败”，Setup方法本身可能会引发NotImplemented错误。有关注册模块，请参阅以下示例：

try:
    from skimage import registration
except ImportError:
    raise NotImplementedError("registration module not available")

在本地测试基准测试

在运行真正的基准测试之前，测试代码是否没有输入错误通常是值得的。要执行此操作，可以使用命令：：

asv dev -b TransformSuite

其中 TransformSuite 以上将在您当前的环境中运行一次，以测试一切是否正常。

运行您的基准测试

上面的命令速度很快，但没有充分测试代码的性能。要做到这一点，您可能希望在当前环境中运行基准测试，以在开发新功能时查看更改的性能。命令 asv run -E existing 将指定您希望在现有环境中运行基准测试。这将节省大量时间，因为构建SCRICIT-IMAGE可能是一项耗时的任务：

asv run -E existing -b TransformSuite

将结果与主结果进行比较

通常，PR的目标是将修改的结果在速度方面与主分支中的代码的快照进行比较 scikit-image 存储库。命令 asv continuous 在这里有帮助：：

asv continuous master -b TransformSuite

此调用将构建在 asv.conf.json 归档并比较当前提交和主分支中的代码之间的基准测试的性能。

输出可能类似于：：

$ asv continuous master -b TransformSuite
· Creating environments
· Discovering benchmarks
·· Uninstalling from conda-py3.7-cython-numpy1.15-scipy
·· Installing 544c0fe3 <benchmark_docs> into conda-py3.7-cython-numpy1.15-scipy.
· Running 4 total benchmarks (2 commits * 2 environments * 1 benchmarks)
[  0.00%] · For scikit-image commit 37c764cb <benchmark_docs~1> (round 1/2):
[...]
[100.00%] ··· ...ansform.TransformSuite.time_hough_line           33.2±2ms

BENCHMARKS NOT SIGNIFICANTLY CHANGED.

在这种情况下，机头和机主之间的差异不足以报告空速。

还可以获得两个特定修订的结果比较，这两个修订的基准结果之前已通过 asv compare 命令：：

asv compare v0.14.5 v0.17.2

最后，您还可以仅为特定的提交散列或发布标签运行ASV基准测试，方法是将 ^! 添加到提交或标记名称。例如，要在v0.17.2版上运行skImage.Filter模块基准：

ASV Run-b过滤器v0.17.2^！