diff options
Diffstat (limited to 'CONTRIBUTING.md')
| -rw-r--r-- | CONTRIBUTING.md | 60 |
1 files changed, 55 insertions, 5 deletions
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2c847319..0052ddf7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,9 +1,27 @@ + # Guidelines For Developers This document provides guidelines for making changes to the fish-shell project. This includes rules for how to format the code, naming conventions, etc. It also includes recommended best practices such as creating a Travis-CI account so you can verify your changes pass all the tests before making a pull-request. See the bottom of this document for help on installing the linting and style reformatting tools discussed in the following sections. +Fish source should limit the C++ features it uses to those available in C++03. That allows fish to use a few components from [C++TR1](https://en.wikipedia.org/wiki/C%2B%2B_Technical_Report_1) such as `shared_ptr`. It also allows fish to be built and run on OS X Snow Leopard (released in 2009); the oldest OS X release we still support. + +## Include What You Use + +You should not depend on symbols being visible to a `*.cpp` module from `#include` statements inside another header file. In other words if your module does `#include "common.h"` and that header does `#include "signal.h"` your module should pretend that sub-include is not present. It should instead directly `#include "signal.h"` if it needs any symbol from that header. That makes the actual dependencies much clearer. It also makes it easy to modify the headers included by a specific header file without having to worry that will break any module (or header) that includes a particular header. + +To help enforce this rule the `make lint` (and `make lint-all`) command will run the [include-what-you-use](http://include-what-you-use.org/) tool. The IWYU you project is on [github](https://github.com/include-what-you-use/include-what-you-use). + +To install the tool on OS X you'll need to add a [formula](https://github.com/jasonmp85/homebrew-iwyu) then install it: + +``` +brew tap jasonmp85/iwyu +brew install iwyu +``` + +On Ubuntu you can install it via `sudo apt-get install iwyu`. + ## Lint Free Code Automated analysis tools like cppcheck and oclint can point out potential bugs. They also help ensure the code has a consistent style and that it avoids patterns that tend to confuse people. @@ -40,7 +58,9 @@ The following sections discuss the specific rules for the style that should be u make style ``` -before commiting your change. If you've already committed your changes that's okay since it will then check the files in the most recent commit. This can be useful after you've merged someone elses change and want to check that it's style is acceptable. +before commiting your change. That will run `git-clang-format` to rewrite just the lines you're modifying. + +If you've already committed your changes that's okay since it will then check the files in the most recent commit. This can be useful after you've merged someone elses change and want to check that it's style is acceptable. However, in that case it will run `clang-format` to ensure the entire file, not just the lines modified by the commit, conform to the style. If you want to check the style of the entire code base run @@ -48,7 +68,35 @@ If you want to check the style of the entire code base run make style-all ``` -### Suppressing Reformatting of the Code +That command will refuse to restyle any files if you have uncommitted changes. + +### Configuring Your Editor for Fish C++ Code + +#### ViM + +As of ViM 7.4 it does not recognize triple-slash comments as used by Doxygen and the OS X Xcode IDE to flag comments that explain the following C symbol. This means the `gq` key binding to reformat such comments doesn't behave as expected. You can fix that by adding the following to your vimrc: + +``` +autocmd Filetype c,cpp setlocal comments^=:/// +``` + +If you use ViM I recommend the [vim-clang-format plugin](https://github.com/rhysd/vim-clang-format) by [@rhysd](https://github.com/rhysd). + +You can also get ViM to provide reasonably correct behavior by installing + +http://www.vim.org/scripts/script.php?script_id=2636 + +#### Emacs + +If you use Emacs: TBD + +### Configuring Your Editor for Fish Scripts + +If you use ViM: TBD + +If you use Emacs: TBD + +### Suppressing Reformatting of C++ Code If you have a good reason for doing so you can tell `clang-format` to not reformat a block of code by enclosing it in comments like this: @@ -60,11 +108,11 @@ code to ignore ## Fish Script Style Guide -Fish scripts such as those in the *share/functions* and *tests* directories should be formatted using the `fish_indent` command. +1. Fish scripts such as those in the *share/functions* and *tests* directories should be formatted using the `fish_indent` command. -Function names should be all lowercase with undescores separating words. Private functions should begin with an underscore. The first word should be `fish` if the function is unique to fish. +1. Function names should be all lowercase with undescores separating words. Private functions should begin with an underscore. The first word should be `fish` if the function is unique to fish. -The first word of global variable names should generally be `fish` for public vars or `_fish` for private vars to minimize the possibility of name clashes with user defined vars. +1. The first word of global variable names should generally be `fish` for public vars or `_fish` for private vars to minimize the possibility of name clashes with user defined vars. ## C++ Style Guide @@ -80,6 +128,8 @@ The first word of global variable names should generally be `fish` for public va 1. Comments should always use the C++ style; i.e., each line of the comment should begin with a `//` and should be limited to 100 characters. Comments that do not begin a line should be separated from the previous text by two spaces. +1. Comments that document the purpose of a function or class should begin with three slashes, `///`, so that OS X Xcode (and possibly other ideas) will extract the comment and show it in the "Quick Help" window when the cursor is on the symbol. + ## Testing The source code for fish includes a large collection of tests. If you are making any changes to fish, running these tests is highly recommended to make sure the behaviour remains consistent. |