|
| 1 | +# Contributing |
| 2 | + |
| 3 | +Below you will find a collection of guidelines for submitting issues as well as contributing code to the Caffe repository. |
| 4 | +Please read those before starting an issue or a pull request. |
| 5 | + |
| 6 | +## Issues |
| 7 | + |
| 8 | +Specific Caffe design and development issues, bugs, and feature requests are maintained by GitHub Issues. |
| 9 | + |
| 10 | +*Please do not post installation, build, usage, or modeling questions, or other requests for help to Issues.* |
| 11 | +Use the [caffe-users list](https://groups.google.com/forum/#!forum/caffe-users) instead. |
| 12 | +This helps developers maintain a clear, uncluttered, and efficient view of the state of Caffe. |
| 13 | +See the chapter [caffe-users](#caffe-users) below for guidance on posting to the users list. |
| 14 | + |
| 15 | +When reporting an issue, it's most helpful to provide the following information, where applicable: |
| 16 | +* How does the problem look like and what steps reproduce it? |
| 17 | +* Can you reproduce it using the latest [master](https://github.com/BVLC/caffe/tree/master), compiled with the `DEBUG` make option? |
| 18 | +* What hardware and software are you running? In particular: |
| 19 | + * GPU make and model, if relevant, |
| 20 | + * operating system/distribution, |
| 21 | + * compiler; please also post which version (for example, with GCC run `gcc --version` to check), |
| 22 | + * CUDA version, if applicable (run `nvcc --version` to check), |
| 23 | + * cuDNN version, if applicable (version number is stored in `cudnn.h`, look for lines containing `CUDNN_MAJOR`, `CUDNN_MINOR` and `CUDNN_PATCHLEVEL`), |
| 24 | + * BLAS library, |
| 25 | + * Python version, if relevant, |
| 26 | + * MATLAB version, if relevant. |
| 27 | +* **What have you already tried** to solve the problem? How did it fail? Are there any other issues related to yours? |
| 28 | +* If this is not a build-related issue, does your installation pass `make runtest`? |
| 29 | +* If the bug is a crash, provide the backtrace (usually printed by Caffe; always obtainable with `gdb`). |
| 30 | +* If you are reporting a build error that seems to be due to a bug in Caffe, please attach your build configuration (either Makefile.config or CMakeCache.txt) and the output of the make (or cmake) command. |
| 31 | + |
| 32 | +If only a small portion of the code/log is relevant to your issue, you may paste it directly into the post, preferably using Markdown syntax for code block: triple backtick ( \`\`\` ) to open/close a block. |
| 33 | +In other cases (multiple files, or long files), please **attach** them to the post - this greatly improves readability. |
| 34 | + |
| 35 | +If the problem arises during a complex operation (e.g. large script using pycaffe, long network prototxt), please reduce the example to the minimal size that still causes the error. |
| 36 | +Also, minimize influence of external modules, data etc. - this way it will be easier for others to understand and reproduce your issue, and eventually help you. |
| 37 | +Sometimes you will find the root cause yourself in the process. |
| 38 | + |
| 39 | +Try to give your issue a title that is succinct and specific. The devs will rename issues as needed to keep track of them. |
| 40 | + |
| 41 | +## Caffe-users |
| 42 | + |
| 43 | +Before you post to the [caffe-users list](https://groups.google.com/forum/#!forum/caffe-users), make sure you look for existing solutions. |
| 44 | +The Caffe community has encountered and found solutions to countless problems - benefit from the collective experience. |
| 45 | +Recommended places to look: |
| 46 | +* the [users list](https://groups.google.com/forum/#!forum/caffe-users) itself, |
| 47 | +* [`caffe`](https://stackoverflow.com/questions/tagged/caffe) tag on StackOverflow, |
| 48 | +* [GitHub issues](https://github.com/BVLC/caffe/issues) tracker (some problems have been answered there), |
| 49 | +* the public [wiki](https://github.com/BVLC/caffe/wiki), |
| 50 | +* the official [documentation](http://caffe.berkeleyvision.org/). |
| 51 | + |
| 52 | +Found a post/issue with your exact problem, but with no answer? |
| 53 | +Don't just leave a "me too" message - provide the details of your case. |
| 54 | +Problems with more available information are easier to solve and attract good attention. |
| 55 | + |
| 56 | +When posting to the list, make sure you provide as much relevant information as possible - recommendations for an issue report (see above) are a good starting point. |
| 57 | +*Please make it very clear which version of Caffe you are using, especially if it is a fork not maintained by BVLC.* |
| 58 | + |
| 59 | +Formatting recommendations hold: paste short logs/code fragments into the post (use fixed-width text for them), **attach** long logs or multiple files. |
| 60 | + |
| 61 | +## Pull Requests |
| 62 | + |
| 63 | +Caffe welcomes all contributions. |
| 64 | + |
| 65 | +See the [contributing guide](http://caffe.berkeleyvision.org/development.html) for details. |
| 66 | + |
| 67 | +Briefly: read commit by commit, a PR should tell a clean, compelling story of _one_ improvement to Caffe. In particular: |
| 68 | + |
| 69 | +* A PR should do one clear thing that obviously improves Caffe, and nothing more. Making many smaller PRs is better than making one large PR; review effort is superlinear in the amount of code involved. |
| 70 | +* Similarly, each commit should be a small, atomic change representing one step in development. PRs should be made of many commits where appropriate. |
| 71 | +* Please do rewrite PR history to be clean rather than chronological. Within-PR bugfixes, style cleanups, reversions, etc. should be squashed and should not appear in merged PR history. |
| 72 | +* Anything nonobvious from the code should be explained in comments, commit messages, or the PR description, as appropriate. |
0 commit comments