发展指南¶
本部分为希望为TomoPy项目做出贡献的开发人员解释基础知识。
使用GitHub¶
克隆存储库¶
该项目在GitHub上维护,GitHub是软件开发人员的版本控制和协作平台。第一个寄存器位于 GitHub and fork (make your own copy of) the TomoPy repository by clicking the Fork button in the header of the TomoPy repository :
这将在您的个人GitHub空间中创建项目的远程副本。接下来,将项目分支的副本克隆到本地计算机。您可以通过单击 Clone in Desktop 右手边栏底部的按钮:
这将启动GitHub桌面应用程序(两者均可用 Mac 和 Win )并询问您要将其保存在哪里。在您的计算机中选择一个位置,并轻松地在代码中进行修改。
提交更改¶
在代码中做了一些更改之后,获取一个 snapshot 你所做的编辑。那就是你做一个 commit 。为此,启动GitHub桌面应用程序,它应该会为您提供自上次提交以来代码中的所有更改。写一篇摘要 Summary 和 Description 关于您所做的更改,然后单击 Commit 按钮:
请记住,您编写这些消息是为了帮助其他人了解您对代码所做的更改。
发布您的更改¶
一旦您觉得您添加的功能将使社区受益,那么您应该考虑回馈TomoPy项目。您需要将本地提交推送到GitHub,然后转到项目的在线GitHub存储库并单击 green 按钮以比较、复查和创建拉式请求。
单击此按钮后,将显示一个审查页面,您可以在其中获得分支分支和原始TomoPy存储库之间到底发生了哪些变化的高级概述。当您准备好提交拉取请求时,请单击 Create pull request :
点击 Create pull request 将您发送到讨论页,您可以在其中输入标题和有用的说明。重要的是要提供尽可能多的有用信息和理由,说明你为什么首先提出这个拉请求。
当你准备好输入你发自内心的论点时,点击 Send pull request 。你完蛋了!
建筑TomoPy¶
安装依赖项¶
要构建和运行TomoPy,您至少需要安装中列出的依赖项 envs/{platform}-{version}.yml
外加基于您的平台的其他依赖项。为方便起见,在Linux上构建Python3.6版本的安装要求可以按如下方式完成:
$ conda env create -f envs/linux-36.yml [-n ENVIRONMENT]
这将使用构建依赖项创建一个名为tomopy的新Conda环境。如果您已经有一个名为tomopy的conda环境。使用 -n 可以选择将其命名为其他名称。
其他Windows要求¶
Windows VC++2017编译器不能通过CONDA分发。该编译器的conda包创建了从系统提供的编译器到安装它的conda环境的链接。使用Windows生成工具安装程序安装VC++2017;生成TomoPy不需要使用Visual Studio(IDE)。
其他CUDA要求¶
CUDA编译器不能通过Conda分发。构建具有GPU功能的TomoPy需要CUDA工具包和NVCC。
编译TomoPy¶
TomoPy被构建/打包成两部分:仅支持python的模块和编译后的共享库。在导入时,Python模块在库路径中搜索已编译的共享库,如果没有找到,则发出错误/警告。因为编译部分和Python部分是分开的,所以开发Python部分不需要构建编译部分;可以使用conda预编译安装编译部分。
TomoPy(仅支持Python的模块)¶
在导航到 tomopy 目录中,您可以通过以典型的Python方式运行安装脚本来安装TomoPy:
$ pip install . --no-deps
运行测试¶
TomoPy有一套Python单元测试,它们位于 /test
目录下的包遵循相同的树形结构。 /tomopy
。当您发出Pull请求时,TravisCI会自动运行这些服务(有关操作方法,请参阅下文)。您可以使用pytest或您喜欢的任何一种python测试运行器来手动运行它们。为了更容易对您对代码所做的更改运行测试,建议您在开发模式下安装TomoPy。 (python setup.py develop )
这个 pytest test runner ,可通过pip或anaconda获得。
要运行测试,请打开终端,导航到项目文件夹,然后运行 py.test
。
要运行测试的部分,请向py.test传递一个目录或文件路径,如下所示 py.test test/test_recon
或 py.test test/test_recon/test_rotation.py
。
在编写测试时,我们至少会尝试使用合成数据检查所有函数返回,以及一些维度、类型等。强烈建议您编写测试!
编码约定¶
我们尽量保持代码的一致性和可读性。因此,在开始编码之前,请记住以下样式和语法指南。
首先,代码应该被很好地记录,易于理解,并很好地集成到项目的其余部分。例如,在编写新函数时,请始终描述其用途和参数:
def my_awesome_func(a, b):
"""
Adds two numbers.
Parameters
----------
a : scalar (float)
First number to add
b : scalar (float)
Second number to add
Returns
-------
output : scalar (float)
Added value
"""
return a+b
包版本控制¶
我们遵循X.Y.Z(主要、次要、补丁) semantic for package versioning 。对于不会更改软件API的微小更改和错误修复,补丁编号会递增。对于添加了新的但向后兼容的API功能的版本,次要版本是递增的,对于不向后兼容的API更改,主要版本是递增的。例如,依赖于API版本2.1.5的软件与版本2.2.3兼容,但不一定与3.2.4兼容。
我们使用git标记来管理我们的版本, setuptools_scm 包裹。