|
|
--- |
|
|
title: Developing and Contributing |
|
|
--- |
|
|
# Development and Contributing |
|
|
|
|
|
Caffe is developed with active participation of the community.<br> |
|
|
The [BAIR](http://bair.berkeley.edu/)/BVLC brewers welcome all contributions! |
|
|
|
|
|
The exact details of contributions are recorded by versioning and cited in our [acknowledgements](http://caffe.berkeleyvision.org/#acknowledgements). |
|
|
This method is impartial and always up-to-date. |
|
|
|
|
|
## License |
|
|
|
|
|
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. |
|
|
|
|
|
## Copyright |
|
|
|
|
|
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. |
|
|
|
|
|
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. |
|
|
|
|
|
### Documentation |
|
|
|
|
|
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`. |
|
|
|
|
|
We prefer tutorials and examples to be documented close to where they live, in `readme.md` files. |
|
|
The `build_docs.sh` script gathers all `examples/**/readme.md` and `examples/*.ipynb` files, and makes a table of contents. |
|
|
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`. |
|
|
Similarly for IPython notebooks: simply include `"include_in_docs": true` in the `"metadata"` JSON field. |
|
|
|
|
|
Other docs, such as installation guides, are written in the `docs` directory and manually linked to from the `index.md` page. |
|
|
|
|
|
We strive to provide lots of usage examples, and to document all code in docstrings. |
|
|
We absolutely appreciate any contribution to this effort! |
|
|
|
|
|
### Versioning |
|
|
|
|
|
The `master` branch receives all new development including community contributions. |
|
|
We try to keep it in a reliable state, but it is the bleeding edge, and things do get broken every now and then. |
|
|
BAIR 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. |
|
|
|
|
|
#### Issues & Pull Request Protocol |
|
|
|
|
|
Post [Issues](https://github.com/BVLC/caffe/issues) to propose features, report [bugs], and discuss framework code. |
|
|
Large-scale development work is guided by [milestones], which are sets of Issues selected for bundling as releases. |
|
|
|
|
|
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. |
|
|
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. |
|
|
|
|
|
**When you are ready to develop a feature or fixing a bug, follow this protocol**: |
|
|
|
|
|
- Develop in [feature branches] with descriptive names. Branch off of the latest `master`. |
|
|
- Bring your work up-to-date by [rebasing] onto the latest `master` when done. |
|
|
(Groom your changes by [interactive rebase], if you'd like.) |
|
|
- [Pull request] your contribution to `BVLC/caffe`'s `master` branch for discussion and review. |
|
|
- Make PRs *as soon as development begins*, to let discussion guide development. |
|
|
- 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! |
|
|
- When the PR satisfies the above properties, use comments to request maintainer review. |
|
|
|
|
|
The following is a poetic presentation of the protocol in code form. |
|
|
|
|
|
#### [Shelhamer's](https://github.com/shelhamer) “life of a branch in four acts” |
|
|
|
|
|
Make the `feature` branch off of the latest `bvlc/master` |
|
|
|
|
|
git checkout master |
|
|
git pull upstream master |
|
|
git checkout -b feature |
|
|
# do your work, make commits |
|
|
|
|
|
Prepare to merge by rebasing your branch on the latest `bvlc/master` |
|
|
|
|
|
# make sure master is fresh |
|
|
git checkout master |
|
|
git pull upstream master |
|
|
# rebase your branch on the tip of master |
|
|
git checkout feature |
|
|
git rebase master |
|
|
|
|
|
Push your branch to pull request it into `BVLC/caffe:master` |
|
|
|
|
|
git push origin feature |
|
|
# ...make pull request to master... |
|
|
|
|
|
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. |
|
|
|
|
|
The pull request of `feature` into `master` will be a clean merge. Applause. |
|
|
|
|
|
[bugs]: https://github.com/BVLC/caffe/issues?labels=bug&page=1&state=open |
|
|
[milestones]: https://github.com/BVLC/caffe/issues?milestone=1 |
|
|
[Pull request]: https://help.github.com/articles/using-pull-requests |
|
|
[interactive rebase]: https://help.github.com/articles/interactive-rebase |
|
|
[rebasing]: http://git-scm.com/book/en/Git-Branching-Rebasing |
|
|
[feature branches]: https://www.atlassian.com/git/workflows#!workflow-feature-branch |
|
|
|
|
|
**Historical note**: Caffe once relied on a two branch `master` and `dev` workflow. |
|
|
PRs from this time are still open but these will be merged into `master` or closed. |
|
|
|
|
|
### Testing |
|
|
|
|
|
Run `make runtest` to check the project tests. New code requires new tests. Pull requests that fail tests will not be accepted. |
|
|
|
|
|
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: |
|
|
|
|
|
# run all tests with CPU in the name |
|
|
build/test/test_all.testbin --gtest_filter='*CPU*' |
|
|
|
|
|
# run all tests without GPU in the name (note the leading minus sign) |
|
|
build/test/test_all.testbin --gtest_filter=-'*GPU*' |
|
|
|
|
|
To get a list of all options `googletest` provides, simply pass the `--help` flag: |
|
|
|
|
|
build/test/test_all.testbin --help |
|
|
|
|
|
### Style |
|
|
|
|
|
- **Run `make lint` to check C++ code.** |
|
|
- Wrap lines at 80 chars. |
|
|
- Follow [Google C++ style](https://google.github.io/styleguide/cppguide.html) and [Google python style](https://google.github.io/styleguide/pyguide.html) + [PEP 8](http://legacy.python.org/dev/peps/pep-0008/). |
|
|
- 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. |
|
|
|
