summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorSergey Karayev <sergeykarayev@gmail.com>2014-07-09 15:06:10 -0700
committerSergey Karayev <sergeykarayev@gmail.com>2014-07-09 15:06:10 -0700
commita7e43ed28f60db23e8fe74ef54bff3771bacb319 (patch)
treef7fec27cf5421c73a6ea18a72282e16334d1f3ab
parentf0cc3f7ee187ae4857c145d2805de19d86acd2fa (diff)
downloadcaffe-a7e43ed28f60db23e8fe74ef54bff3771bacb319.tar.gz
caffe-a7e43ed28f60db23e8fe74ef54bff3771bacb319.tar.bz2
caffe-a7e43ed28f60db23e8fe74ef54bff3771bacb319.zip
[docs] got rid of redundant README, updated development instructions
-rw-r--r--README.md116
-rw-r--r--docs/development.md104
2 files changed, 80 insertions, 140 deletions
diff --git a/README.md b/README.md
index 6b45624f..fb2f98d4 100644
--- a/README.md
+++ b/README.md
@@ -1,115 +1,3 @@
-[Caffe: Convolutional Architecture for Fast Feature Extraction](http://caffe.berkeleyvision.org)
+Caffe: Convolutional Architecture for Fast Feature Embedding
-Created by [Yangqing Jia](http://daggerfs.com), UC Berkeley EECS department.
-In active development by the Berkeley Vision and Learning Center ([BVLC](http://bvlc.eecs.berkeley.edu/)).
-
-## Introduction
-
-Caffe aims to provide computer vision scientists with a **clean, modifiable
-implementation** of state-of-the-art deep learning algorithms. Network structure
-is easily specified in separate config files, with no mess of hard-coded
-parameters in the code. Python and Matlab wrappers are provided.
-
-At the same time, Caffe fits industry needs, with blazing fast C++/Cuda code for
-GPU computation. Caffe is currently the fastest GPU CNN implementation publicly
-available, and is able to process more than **40 million images per day** on a
-single NVIDIA K40 GPU (or 20 million per day on a K20)\*.
-
-Caffe also provides **seamless switching between CPU and GPU**, which allows one
-to train models with fast GPUs and then deploy them on non-GPU clusters with one
-line of code: `Caffe::set_mode(Caffe::CPU)`.
-
-Even in CPU mode, computing predictions on an image takes only 20 ms when images
-are processed in batch mode.
-
-* [Caffe introductory presentation](https://www.dropbox.com/s/10fx16yp5etb8dv/caffe-presentation.pdf)
-* [Installation instructions](http://caffe.berkeleyvision.org/installation.html)
-
-\* When measured with the [SuperVision](http://www.image-net.org/challenges/LSVRC/2012/supervision.pdf) model that won the ImageNet Large Scale Visual Recognition Challenge 2012.
-
-## License
-
-Caffe is BSD 2-Clause licensed (refer to the
-[LICENSE](http://caffe.berkeleyvision.org/license.html) for details).
-
-The pretrained models published by the BVLC, such as the
-[Caffe reference ImageNet model](https://www.dropbox.com/s/n3jups0gr7uj0dv/caffe_reference_imagenet_model)
-are licensed for academic research / non-commercial use only. However, Caffe is
-a full toolkit for model training, so start brewing your own Caffe model today!
-
-## Citing Caffe
-
-Please kindly cite Caffe in your publications if it helps your research:
-
- @misc{Jia13caffe,
- Author = {Yangqing Jia},
- Title = { {Caffe}: An Open Source Convolutional Architecture for Fast Feature Embedding},
- Year = {2013},
- Howpublished = {\url{http://caffe.berkeleyvision.org/}}
- }
-
-## Documentation
-
-Tutorials and general documentation are written in Markdown format in the `docs/` folder.
-While the format is quite easy to read directly, you may prefer to view the whole thing as a website.
-To do so, simply run `jekyll serve -s docs` and view the documentation website at `http://0.0.0.0:4000` (to get [jekyll](http://jekyllrb.com/), you must have ruby and do `gem install jekyll`).
-
-We strive to provide provide lots of usage examples, and to document all code in docstrings.
-We'd appreciate your contribution to this effort!
-
-## Development
-
-Caffe is developed with active participation of the community by the [Berkeley Vision and Learning Center](http://bvlc.eecs.berkeley.edu/).
-We welcome all contributions!
-
-### The release cycle
-
-- The `dev` branch is for new development, including community contributions. We aim to keep it in a functional state, but large changes may occur and things may get broken every now and then. Use this if you want the "bleeding edge".
-- The `master` branch is handled by BVLC, which will integrate changes from `dev` on a roughly monthly schedule, giving it a release tag. Use this if you want more stability.
-
-### Setting priorities
-
-- Make GitHub Issues for bugs, features you'd like to see, questions, etc.
-- Development work is guided by [milestones](https://github.com/BVLC/caffe/issues?milestone=1), which are sets of issues selected for concurrent release (integration from `dev` to `master`).
-- Please note that since the core developers are largely researchers, we may work on a feature in isolation from the open-source community for some time before releasing it, so as to claim honest academic contribution. We do release it as soon as a reasonable technical report may be written about the work, and we still aim to inform the community of ongoing development through Issues.
-
-### Contibuting
-
-- Do new development in [feature branches](https://www.atlassian.com/git/workflows#!workflow-feature-branch) with descriptive names.
-- Bring your work up-to-date by [rebasing](http://git-scm.com/book/en/Git-Branching-Rebasing) onto the latest `dev`. (Polish your changes by [interactive rebase](https://help.github.com/articles/interactive-rebase), if you'd like.)
-- [Pull request](https://help.github.com/articles/using-pull-requests) your contribution to BVLC/caffe's `dev` branch for discussion and review.
- * PRs should live fast, die young, and leave a beautiful merge. Pull request sooner than later so that discussion can guide development.
- * Code must be accompanied by documentation and tests at all times.
- * Only fast-forward merges will be accepted.
-
-See our [development guidelines](http://caffe.berkeleyvision.org/development.html) for further details–the more closely these are followed, the sooner your work will be merged.
-
-#### [Shelhamer's](https://github.com/shelhamer) “life of a branch in four acts”
-
-Make the `feature` branch off of the latest `bvlc/dev`
-```
-git checkout dev
-git pull upstream dev
-git checkout -b feature
-# do your work, make commits
-```
-
-Prepare to merge by rebasing your branch on the latest `bvlc/dev`
-```
-# make sure dev is fresh
-git checkout dev
-git pull upstream dev
-# rebase your branch on the tip of dev
-git checkout feature
-git rebase dev
-```
-
-Push your branch to pull request it into `dev`
-```
-git push origin feature
-# ...make pull request to dev...
-```
-
-Now make a pull request! You can do this from the command line (`git pull-request -b dev`) if you install [hub](https://github.com/github/hub).
-
-The pull request of `feature` into `dev` will be a clean merge. Applause.
+Consult the [project website](http://caffe.berkeleyvision.org) for all documentation.
diff --git a/docs/development.md b/docs/development.md
index ea18d5cf..444c9e8e 100644
--- a/docs/development.md
+++ b/docs/development.md
@@ -2,39 +2,89 @@
layout: default
title: Development
---
+# Development
-Developing & Contributing
-=========================
+Caffe is developed with active participation of the community.<br />
+The [BVLC](http://bvlc.eecs.berkeley.edu/) maintainers welcome all contributions!
-Caffe is developed with active participation of the community by the [Berkeley Vision and Learning Center](http://bvlc.eecs.berkeley.edu/).
-We welcome all contributions!
+### Documentation
-The [contributing workflow](https://github.com/BVLC/caffe#development) is explained in the README. These guidelines cover development practices in Caffe. This is a work-in-progress.
+Tutorials and general documentation -- including this website -- are written in Markdown format in the `docs/` folder.
+While the format is quite easy to read directly, you may prefer to view the whole thing as a website.
+To do so, simply run `jekyll serve -s docs` and view the documentation website at `http://0.0.0.0:4000` (for [jekyll](http://jekyllrb.com/), you must have ruby and do `gem install jekyll`).
-**Development Flow**
+We strive to provide provide lots of usage examples, and to document all code in docstrings.
+We absolutely appreciate any contribution to this effort!
-- `master` is golden.
-- `dev` is for new development: it is the branching point for features and the base of pull requests.
- * The history of `dev` is not rewritten.
- * Contributions are shepherded from `dev` to `master` by BVLC by merge.
-- To err is human. Accidents are fixed by reverts.
-- Releases are marked with tags on merge from `dev` to `master`.
+### The release cycle
-**Issues & Pull Request Protocol**
+- The `dev` branch receives all new development, including community contributions.
+We aim to keep it in a functional state, but large changes do occur, and things do get broken every now and then.
+Use only if you want the "bleeding edge".
+- BVLC maintainers will periodically update the `master` branch with changes from `dev`, giving it a release tag ([releases so far](https://github.com/BVLC/caffe/releases)).
+Use this if you want more stability.
-0. Make issues for [bugs](https://github.com/BVLC/caffe/issues?labels=bug&page=1&state=open), tentative proposals, and [questions](https://github.com/BVLC/caffe/issues?labels=question&page=1&state=open).
-1. Make PRs to signal development:
- a. Make PRs *as soon as development begins*. Create a feature branch, make your initial commit, push, and PR to let everyone know you are working on it and let discussion guide development instead of review development after-the-fact.
- b. When a proposal from the first step earns enough interest to warrant development, make a PR, and reference and close the old issue to direct the conversation to the PR.
-2. When a PR is ready, comment to request a maintainer be assigned to review and merge to `dev`.
+### Issues & Pull Request Protocol
-A PR is only ready for review when the code is committed, documented, linted, and tested!
+Use Github Issues to report [bugs], propose features, and ask [questions].
+Large-scale development work is guided by [milestones], which are sets of Issues selected for concurrent release (integration from `dev` to `master`).
-**Documentation**: the documentation is bundled with Caffe in `docs/`. This includes the site you are reading now. Contributions should be documented both inline in code and through usage examples. New documentation is published by BVLC with each release and between releases as-needed.
+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.
-We'd appreciate your contribution to the documentation effort!
+When you are ready to start developing your feature or fixing a bug, follow this protocol:
-**Testing**: run `make runtest` to check the project tests. New code requires new tests. Pull requests that fail tests will not be accepted.
+- Do new development in [feature branches] with descriptive names.
+- Bring your work up-to-date by [rebasing] onto the latest `dev`.
+(Polish your changes by [interactive rebase], if you'd like.)
+- [Pull request] your contribution to `BVLC/caffe`'s `dev` 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 to dev, 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.
+
+Below 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/dev`
+```
+git checkout dev
+git pull upstream dev
+git checkout -b feature
+# do your work, make commits
+```
+
+Prepare to merge by rebasing your branch on the latest `bvlc/dev`
+```
+# make sure dev is fresh
+git checkout dev
+git pull upstream dev
+# rebase your branch on the tip of dev
+git checkout feature
+git rebase dev
+```
+
+Push your branch to pull request it into `dev`
+```
+git push origin feature
+# ...make pull request to dev...
+```
+
+Now make a pull request! You can do this from the command line (`git pull-request -b dev`) if you install [hub](https://github.com/github/hub).
+
+The pull request of `feature` into `dev` will be a clean merge. Applause.
+
+[bugs]: https://github.com/BVLC/caffe/issues?labels=bug&page=1&state=open
+[questions]: https://github.com/BVLC/caffe/issues?labels=question&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
+
+### Testing
+
+Run `make runtest` to check the project tests. New code requires new tests. Pull requests that fail tests will not be accepted.
The `googletest` 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:
@@ -48,16 +98,18 @@ To get a list of all options `googletest` provides, simply pass the `--help` fla
build/test/test_all.testbin --help
-**Style**
+### Style
- 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/).
- Wrap lines at 80 chars.
- 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.
+- **Run `make lint` to check C++ code.**
-**Lint**: run `make lint` to check C++ code.
+### Copyright
-**Copyright**: assign copyright jointly to BVLC and contributors like so:
+Assign copyright jointly to BVLC and contributors like so:
// Copyright 2014 BVLC and contributors.
-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.
+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.