docs/development.md

   1 ---
   2 title: Developing and Contributing
   3 ---
   4 # Development and Contributing
   5
   6 Caffe is developed with active participation of the community.<br>
   7 The [BVLC](http://bvlc.eecs.berkeley.edu/) brewers welcome all contributions!
   8
   9 The exact details of contributions are recorded by versioning and cited in our [acknowledgements](http://caffe.berkeleyvision.org/#acknowledgements).
  10 This method is impartial and always up-to-date.
  11
  12 ## License
  13
  14 Caffe is licensed under the terms in [LICENSE](https://github.com/BVLC/caffe/blob/master/LICENSE). By contributing to the project, you agree to the license and copyright terms therein and release your contribution under these terms.
  15
  16 ## Copyright
  17
  18 Caffe uses a shared copyright model: each contributor holds copyright over their contributions to Caffe. The project versioning records all such contribution and copyright details.
  19
  20 If a contributor wants to further mark their specific copyright on a particular contribution, they should indicate their copyright solely in the commit message of the change when it is committed. Do not include copyright notices in files for this purpose.
  21
  22 ### Documentation
  23
  24 This website, written with [Jekyll](http://jekyllrb.com/), acts as the official Caffe documentation -- simply run `scripts/build_docs.sh` and view the website at `http://0.0.0.0:4000`.
  25
  26 We prefer tutorials and examples to be documented close to where they live, in `readme.md` files.
  27 The `build_docs.sh` script gathers all `examples/**/readme.md` and `examples/*.ipynb` files, and makes a table of contents.
  28 To be included in the docs, the readme files must be annotated with [YAML front-matter](http://jekyllrb.com/docs/frontmatter/), including the flag `include_in_docs: true`.
  29 Similarly for IPython notebooks: simply include `"include_in_docs": true` in the `"metadata"` JSON field.
  30
  31 Other docs, such as installation guides, are written in the `docs` directory and manually linked to from the `index.md` page.
  32
  33 We strive to provide lots of usage examples, and to document all code in docstrings.
  34 We absolutely appreciate any contribution to this effort!
  35
  36 ### Versioning
  37
  38 The `master` branch receives all new development including community contributions.
  39 We try to keep it in a reliable state, but it is the bleeding edge, and things do get broken every now and then.
  40 BVLC maintainers will periodically make releases by marking stable checkpoints as tags and maintenance branches. [Past releases](https://github.com/BVLC/caffe/releases) are catalogued online.
  41
  42 #### Issues & Pull Request Protocol
  43
  44 Post [Issues](https://github.com/BVLC/caffe/issues) to propose features, report [bugs], and discuss framework code.
  45 Large-scale development work is guided by [milestones], which are sets of Issues selected for bundling as releases.
  46
  47 Please note that since the core developers are largely researchers, we may work on a feature in isolation for some time before releasing it to the community, so as to claim honest academic contribution.
  48 We do release things as soon as a reasonable technical report may be written, and we still aim to inform the community of ongoing development through Github Issues.
  49
  50 **When you are ready to develop a feature or fixing a bug, follow this protocol**:
  51
  52 - Develop in [feature branches] with descriptive names. Branch off of the latest `master`.
  53 - Bring your work up-to-date by [rebasing] onto the latest `master` when done.
  54 (Groom your changes by [interactive rebase], if you'd like.)
  55 - [Pull request] your contribution to `BVLC/caffe`'s `master` branch for discussion and review.
  56   - Make PRs *as soon as development begins*, to let discussion guide development.
  57   - A PR is only ready for merge review when it is a fast-forward merge, and all code is documented, linted, and tested -- that means your PR must include tests!
  58 - When the PR satisfies the above properties, use comments to request maintainer review.
  59
  60 The following is a poetic presentation of the protocol in code form.
  61
  62 #### [Shelhamer's](https://github.com/shelhamer) “life of a branch in four acts”
  63
  64 Make the `feature` branch off of the latest `bvlc/master`
  65
  66     git checkout master
  67     git pull upstream master
  68     git checkout -b feature
  69     # do your work, make commits
  70
  71 Prepare to merge by rebasing your branch on the latest `bvlc/master`
  72
  73     # make sure master is fresh
  74     git checkout master
  75     git pull upstream master
  76     # rebase your branch on the tip of master
  77     git checkout feature
  78     git rebase master
  79
  80 Push your branch to pull request it into `BVLC/caffe:master`
  81
  82     git push origin feature
  83     # ...make pull request to master...
  84
  85 Now make a pull request! You can do this from the command line (`git pull-request -b master`) if you install [hub](https://github.com/github/hub). Hub has many other magical uses.
  86
  87 The pull request of `feature` into `master` will be a clean merge. Applause.
  88
  89 [bugs]: https://github.com/BVLC/caffe/issues?labels=bug&page=1&state=open
  90 [milestones]: https://github.com/BVLC/caffe/issues?milestone=1
  91 [Pull request]: https://help.github.com/articles/using-pull-requests
  92 [interactive rebase]: https://help.github.com/articles/interactive-rebase
  93 [rebasing]: http://git-scm.com/book/en/Git-Branching-Rebasing
  94 [feature branches]: https://www.atlassian.com/git/workflows#!workflow-feature-branch
  95
  96 **Historical note**: Caffe once relied on a two branch `master` and `dev` workflow.
  97 PRs from this time are still open but these will be merged into `master` or closed.
  98
  99 ### Testing
 100
 101 Run `make runtest` to check the project tests. New code requires new tests. Pull requests that fail tests will not be accepted.
 102
 103 The `gtest` framework we use provides many additional options, which you can access by running the test binaries directly. One of the more useful options is `--gtest_filter`, which allows you to filter tests by name:
 104
 105     # run all tests with CPU in the name
 106     build/test/test_all.testbin --gtest_filter='*CPU*'
 107
 108     # run all tests without GPU in the name (note the leading minus sign)
 109     build/test/test_all.testbin --gtest_filter=-'*GPU*'
 110
 111 To get a list of all options `googletest` provides, simply pass the `--help` flag:
 112
 113     build/test/test_all.testbin --help
 114
 115 ### Style
 116
 117 - **Run `make lint` to check C++ code.**
 118 - Wrap lines at 80 chars.
 119 - Follow [Google C++ style](http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml) and [Google python style](http://google-styleguide.googlecode.com/svn/trunk/pyguide.html) + [PEP 8](http://legacy.python.org/dev/peps/pep-0008/).
 120 - Remember that “a foolish consistency is the hobgoblin of little minds,” so use your best judgement to write the clearest code for your particular case.