Developer Start Guide

Contributing

你想贡献给Theano吗?太棒了!本页解释我们的工作流程和一些资源。

寻找第一份贡献的想法?使用标签easy 修复检查github问题他们是好的开始。它建议你写在你想工作的问题上。这有助于确保它是最新的,看看没有人在做它。此外,我们有时可以提供更多的信息。还有标签NeedSomeoneToFinish是interresting检查。难度级别是可变的。

Resources

有关Theano资源的列表,请参见Community以下组/邮件列表对Theano贡献者特别有用:theano-devtheano-buildbottheano-github

要达到速度,你需要

Requirements for Quality Contributions

  • 所有的代码应该正确测试。
  • 代码应该与Python 2.7及更高版本,以及Python 3.3及更高版本(如果需要,使用)兼容。
  • 所有代码都应遵守PEP8代码风格指南
  • 所有类和函数的文档字符串应遵守PEP257规则并遵循Numpy docstring标准

每个点将在下面更详细地参考。

Unit tests

当您提交拉取请求时,您的更改将自动通过Travis-CI进行测试。这将在你的提交旁边显示一个小图标来发布测试的结果。黄色圆圈表示测试正在运行。红色X表示测试失败,绿色圆圈表示测试通过。

只是因为测试自动运行并不意味着你不应该自己运行它们,以确保一切都是正确的。你可以只运行你正在修改的部分去更快,有travis,以确保没有全局影响。

另外,如果你正在改变GPU代码,travis不会测试,因为测试节点上没有GPU。

要使用默认选项运行测试套件,请参阅How to test that Theano works properly

每天晚上,我们自动执行所有的单元测试,有几组选项。结果将通过电子邮件发送到theano-buildbot邮件列表。

有关详细信息,请参见The nightly build/tests process

要使用与buildbot相同的配置运行所有测试,请运行以下脚本:

theano/misc/do_nightly_build

此脚本接受它转发到nosetests的参数。你可以只运行一些测试或通过给出等效的nosetests参数来启用pdb。

Setting up your Editor for PEP8

以下是VimEmacs的说明。如果您对其他文本编辑器或IDE有类似的说明,请告知我们,我们将更新此文档。

Vim

警告和错误的检测由pep8脚本(或flake8,也检查其他事情,如语法错误)完成。对Vim的语法高亮和一般集成由Vim的Syntastic插件完成。

设置VIM:

  1. 安装flake8(如果尚未安装):

    pip install "flake8<3"
    

    警告

    从版本3.0.0开始,flake8改变了它的依赖性,并将其Python API移动到了一个遗留的模块,打破了Theano的flake8测试。我们建议使用3之前的版本。

    注意

    你可以使用easy_install而不是pippep8而不是flake8重要的是,flake8pep8可执行文件会在你的$PATH中结束。

  2. 安装vundle:

    git clone https://github.com/VundleVim/Vundle.vim.git ~/.vim/bundle/Vundle.vim
    
  3. 编辑~/.vimrc并添加以下行:

    set nocompatible              " be iMproved, required
    filetype off                  " required
    " set the runtime path to include Vundle and initialize
    set rtp+=~/.vim/bundle/Vundle.vim
    call vundle#begin()
    
    Plugin 'gmarik/Vundle.vim' " let Vundle manage Vundle (required!)
    Plugin 'scrooloose/syntastic'
    Plugin 'jimf/vim-pep8-text-width'
    
    call vundle#end()
    
    " Syntastic settings
    " You can run checkers explicitly by calling :SyntasticCheck <checker
    let g:syntastic_python_checkers = ['flake8'] "use one of the following checkers:
                                                 " flake8, pyflakes, pylint, python (native checker)
    let g:syntastic_enable_highlighting = 1  "highlight errors and warnings
    let g:syntastic_style_error_symbol = ">>" "error symbol
    let g:syntastic_warning_symbol = ">>" "warning symbol
    let g:syntastic_check_on_open = 1
    let g:syntastic_auto_jump = 0  "do not jump to errors when detected
    
  4. 打开一个新的vim并运行:PluginInstall以自动安装插件。安装完成后,使用:q关闭安装“窗口”。从现在开始,Vim将检查PEP8错误并在保存文件时突出显示它们。

A few useful commands
  • 打开错误列表::lopen,可以缩写为:lop(表示为:lop[en])。
  • 关闭该列表::lcl[ose]
  • 下一个错误::lne[xt]
  • 上一个错误::lp[revious]

一旦你修复错误,消息和突出显示仍将出现在固定的文件,直到你再次保存。

我们还可以配置~/.vimrc,使其更容易使用Syntastic。例如,要在状态栏中添加摘要,您可以添加:

set statusline+=%{SyntasticStatuslineFlag()}

要绑定F2和F3导航到上一个和下一个错误,您可以添加:

map <F2> :lprevious<CR>
map <F3> :lnext<CR>

如果您希望这些绑定只适用于Python文件,您可以通过autocmd FileType python

Emacs

有一个优秀的系统来配置Python的emacs:emacs-for-python它收集许多emacs配置到一个,并修改他们一起行动好。你可以使用它来检查pep8合规性和Python语法错误。

要在Linux上安装它,你可以这样做:

cd
git clone https://github.com/gabrielelanaro/emacs-for-python.git ~/.emacs.d/emacs-for-python

然后在你的~/.emacs文件中,添加:

;; Mandatory
(load-file "~/.emacs.d/emacs-for-python/epy-init.el")
(add-to-list 'load-path "~/.emacs.d/emacs-for-python/") ;; tell where to load the various files

;; Each of them enables different parts of the system.
;; Only the first two are needed for pep8, syntax check.
(require 'epy-setup) ;; It will setup other loads, it is required!
(require 'epy-python) ;; If you want the python facilities [optional]
(require 'epy-completion) ;; If you want the autocompletion settings [optional]
(require 'epy-editing) ;; For configurations related to editing [optional]
;; [newer version of emacs-for-python]
(require 'epy-nose) ;; For shortcut to call nosetests [optional]

;; Define f10 to previous error
;; Define f11 to next error
(require 'epy-bindings) ;; For my suggested keybindings [optional]

;; Some shortcut that do not collide with gnome-terminal,
;; otherwise, "epy-bindings" define f10 and f11 for them.
(global-set-key [f2] 'flymake-goto-prev-error)
(global-set-key [f3] 'flymake-goto-next-error)

;; Next two lines are the checks to do. You can add more if you wish.
(epy-setup-checker "pyflakes %f") ;; For python syntax check
(epy-setup-checker "pep8 -r %f") ;; For pep8 check

注意

该脚本突出显示有问题的行。这可能使得该行的一部分根据背景不可读。要用下划线替换行突出显示,请将其添加到您的emacs配置文件中:

;;当有警告时,使线条可读。[可选](custom-set-faces'(flymake-errline(((class color))(:underline“red”)))'颜色))(:下划线“黄色”)))))

Documentation and docstrings

A Docstring Example

这里是一个如何添加一个docstring到类的例子。

import theano

class DoubleOp(theano.Op):
    """
    Double each element of a tensor.

    Parameters
    ----------
    x : tensor
        Input tensor

    Returns
    -------
    tensor
        a tensor of the same shape and dtype as the input with all
        values doubled.

    Notes
    -----
    this is a test note

    See Also
    --------
    :class:`~theano.tensor.elemwise.Elemwise` : You can use this to replace
    this example.  Just execute `x * 2` with x being a Theano variable.


    .. versionadded:: 0.6
    """

这是它将显示我们在库文档中自动列出的文件:

class theano.misc.doubleop.DoubleOp(use_c_code='/usr/bin/g++')[source]

双张张量的每个元素。

参数:x - 输入张量。
返回:与所有值加倍的输入具有相同形状和类型的张量。
注意:这是一个测试笔记
也可以看看:你可以使用elemwise op来替换这个例子。只需执行x * 2,x是一个Theano变量。

版本0.6中的新功能。

Installation and configuration

要获取开发者访问权限:向GitHub注册并创建Theano的分支。

这将在GitHub上创建你自己的Theano项目,以后称为“YourProfile / Theano”或“origin”,从中你将能够贡献原来的Theano / Theano,也称为“中央”。

Create a local copy

克隆你的叉在本地

git clone git@github.com:YOUR_GITHUB_LOGIN/Theano.git

要使此网址正常工作,您必须在您的github帐户设置中设置您的公共ssh密钥。

从你的本地存储库,你自己在GitHub上的fork将被称为“origin”。

然后,添加对原始(“中心”)Theano存储库的引用

git remote add central git://github.com/Theano/Theano.git

你可以选择另一个名字比“中央”来引用Theano / Theano(例如,NumPy使用“upstream”),但这个文档将坚持“中心”。

你可以按照How to test that Theano works properly的步骤来测试你的Theano的安装。

Using your local copy

要更新你的库到最新的版本,你应该有一个本地分支,跟踪中央/主。你可以添加一个(在这里命名为“trunk”):

git fetch central
git branch trunk central/master

一旦你有这样的分支,为了更新它,做:

git checkout trunk
git pull

请记住,这个分支应该是“只读”:如果你想修补Theano,你应该在另一个分支工作,如下面Development Workflow部分所述。

Configure Git

在你的本地机器上,你需要配置git的基本信息:

git config --global user.email you@yourdomain.example.com
git config --global user.name "Your Name Comes Here"

你也可以指示git使用diff中的颜色。为此,你需要在文件〜/ .gitconfig中添加这些行

[color]
   branch = auto
   diff = auto
   interactive = auto
   status = auto

Development Workflow

Start a new local branch

当在你自己的fork中使用新功能时,从中央存储库(GitHub上的Theano / Theano)的分支(主要分支)的最新副本开始:

git fetch central
git checkout -b my_shiny_feature central/master

注意

最后一行是一个快捷方式:

git branch my_shiny_feature central/master
git checkout my_shiny_feature

Submit your changes to the central repository

一旦你的代码准备好供别人审查,你需要提交所有的更改,然后推你的分支到你的github fork first:

git commit -a -m "your message here"
git push -u origin my_shiny_feature

然后,在github网站上找到你的fork的github页面,选择你的功能分支,然后点击右上角的“Pull Request”按钮。这将通知维护者您希望提交您的更改包含在中央/主。如果你没有得到任何反馈,错误我们在theano-dev邮件列表。

Address reviewer comments

你的pull请求将由核心开发团队的成员审核。如果你的分支没有被直接接受,评论者将使用GitHub的系统来添加相对于特定代码行的“注释”,一般(在整个提交)或“行注释”。为了让pull请求被接受,你可能需要回答评论者的问题,你可以在GitHub上这样做。

你也可能需要编辑你的代码来解决他们的问题。一些常见的请求包括在注释中修改拼写错误,添加或更正注释,在测试套件中添加单元测试。为了做到这一点,你应该在你使用的同一个分支中继续你的编辑(在这个例子中,“my_shiny_feature”)。例如,如果你改了你的工作分支,你应该先:

git checkout my_shiny_feature

然后,编辑你的代码,并进行适当的测试(参见Requirements for Quality Contributions),并将它再次推送到你的GitHub fork,就像第一次(除了-u

git push origin my_shiny_feature

然后,对中央存储库的pull请求将由GitHub自动更新。但是,审核人不会自动通知您的修订,因此建议您回复对GitHub的意见,让他们知道您已提交修订。

More Advanced Git Usage

您可以在numpy开发页面中找到信息和提示。这里有几个。

Cleaning up branches

当你的pull请求已经合并,你可以从你的GitHub fork的分支列表中删除分支。这是有用的,以避免有太多的分支停留在那里。删除此远程分支是通过以下方式实现的:

git push origin :my_shiny_feature

这行代码推送到“origin”仓库(你在GitHub上的Theano的fork),进入分支“my_shiny_feature”,一个空的内容(这就是为什么冒号之前没有什么),有效地删除它。

该分支将仍然存在于您的本地克隆版本库中。如果你想从那里删除它,你可以运行:

git branch -d my_shiny_feature

Amending a submitted pull request

如果你想修复一个已经提交的提交请求(例如修复一个小的错字),在pull请求被接受之前,你可以这样做,以保持历史清洁:

git checkout my_shiny_feature
git commit --amend
git push origin my_shiny_feature:my_shiny_feature

不要滥用该命令,并且只有当只有小问题需要照顾时才使用它。否则,变得难以使评论者做出的评论与新的修改匹配。在一般情况下,你应该坚持上面描述的方法。

Cleaning up history

有时你可能会在你的特性分支中提交在最终pull请求中不需要的。有一个说明这一点。综上所述:

  • 提交到树干应该比提交给你的功能分支更干净;不只是为了方便审查,而且因为中间提交可以打破怪(平分工具)。
  • git merge -squash将把你的特性分支中的所有提交都放到一个提交中。
  • 如果你的分支对于一个南瓜太大了,还有其他工具是有用的。

Add another distant repository

要与另一个用户合作,他正在开发的一些功能,并且没有准备好包括在中央,最简单的方法是使用他们的Theano分支(通常在GitHub上)。

就像我们添加了Theano / Theano作为远程存储库,命名为“central”,你可以添加(在你的本地机器上)对他们的fork作为一个新的远程存储库的引用。REPO_NAME是您选择命名此分支的名称,GIT_REPO_PATH是有问题的分支的URL。

git remote add REPO_NAME GIT_REPO_PATH

然后,您可以根据来自远程存储库(REPO_NAME)的特定分支(REMOTE_BRANCH_NAME)创建一个新的本地分支(LOCAL_BRANCH_NAME):

git checkout -b LOCAL_BRANCH_NAME REPO_NAME/REMOTE_BRANCH_NAME

Other tools that can help you

  • cProfile:在功能级别工作的时间分析器。
  • :用于剖析编译扩展的模块。
  • autopep8:自动格式化Python代码以符合PEP 8风格指南的工具。
  • line_profiler:逐行分析器。
  • memory_profiler:memory profiler
  • runsnake:Gui for cProfile(time profiler)和Meliae(memory profiler)
  • Guppy:支持对象和堆内存大小,分析和调试。
  • hub:将github命令添加到git命令行的工具。
  • git pull-requests:git / github命令行的另一个工具。