Mirrors/fish-shell
2
0
Fork 0
mirror of https://github.com/fish-shell/fish-shell synced 2024-12-25 20:33:08 +00:00
Code Issues Projects Releases Packages Wiki Activity

Various fixes to CONTRIBUTING.md

Browse source
This commit is contained in:
Donovan Glover 2018-01-28 13:09:52 -05:00 committed by David Adam
parent d03aff8742
commit ac8fe1e4b9
1 changed files with 22 additions and 22 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

44
CONTRIBUTING.md
View file

@ -1,6 +1,6 @@
# Guidelines For Developers # 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, etcetera. Generally known as the style of the code. 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. This document provides guidelines for making changes to the fish-shell project. This includes rules for how to format the code, naming conventions, etcetera. Generally known as the style of the code. It also includes recommended best practices such as creating a Travis CI account so you can verify that 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. See the bottom of this document for help on installing the linting and style reformatting tools discussed in the following sections.
@ -145,7 +145,7 @@ However, as I write this there are no places in the code where we use this and I
1. All fish scripts, such as those in the *share/functions* and *tests* directories, should be formatted using the `fish_indent` command. 1. All fish scripts, such as those in the *share/functions* and *tests* directories, should be formatted using the `fish_indent` command.
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. 1. Function names should be in all lowercase with words separated by underscores. Private functions should begin with an underscore. The first word should be `fish` if the function is unique to fish.
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. 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.
@ -155,7 +155,7 @@ However, as I write this there are no places in the code where we use this and I
1. The `clang-format` command is authoritative with respect to indentation, whitespace around operators, etc. 1. The `clang-format` command is authoritative with respect to indentation, whitespace around operators, etc.
1. All names in code should be `small_snake_case`. No Hungarian notation is used. Classes and structs names should be followed by `_t`. 1. All names in code should be `small_snake_case`. No Hungarian notation is used. The names for classes and structs should be followed by `_t`.
1. Always attach braces to the surrounding context. 1. Always attach braces to the surrounding context.
@ -163,13 +163,13 @@ However, as I write this there are no places in the code where we use this and I
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 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 IDE's) will extract the comment and show it in the "Quick Help" window when the cursor is on the symbol. 1. Comments that document the purpose of a function or class should begin with three slashes, `///`, so that OS X Xcode (and possibly other IDEs) will extract the comment and show it in the "Quick Help" window when the cursor is on the symbol.
## Testing ## Testing
The source code for fish includes a large collection of tests. If you are making any changes to fish, running these tests is mandatory to make sure the behaviour remains consistent and regressions are not introduced. Even if you don't run the tests they will be run via the [Travis CI](https://travis-ci.org/fish-shell/fish-shell) service. The source code for fish includes a large collection of tests. If you are making any changes to fish, running these tests is mandatory to make sure the behaviour remains consistent and regressions are not introduced. Even if you don't run the tests on your machine, they will still be run via the [Travis CI](https://travis-ci.org/fish-shell/fish-shell) service.
You are strongly encouraged to add tests when changing the functionality of fish. Especially if you are fixing a bug to help ensure there are no regressions in the future (i.e., we don't reintroduce the bug). You are strongly encouraged to add tests when changing the functionality of fish, especially if you are fixing a bug to help ensure there are no regressions in the future (i.e., we don't reintroduce the bug).
### Local testing ### Local testing
@ -183,12 +183,12 @@ Running the tests is only supported from the autotools build and not xcodebuild.
### Travis CI Build and Test ### Travis CI Build and Test
The Travis Continuous Integration services can be used to test your changes using multiple configurations. This is the same service that the fish shell project uses to ensure new changes haven't broken anything. Thus it is a really good idea that you leverage Travis CI before making a pull-request to avoid embarrasment at breaking the build. The Travis Continuous Integration services can be used to test your changes using multiple configurations. This is the same service that the fish shell project uses to ensure new changes haven't broken anything. Thus it is a really good idea that you leverage Travis CI before making a pull request to avoid potential embarrassment at breaking the build.
You will need to [fork the fish-shell repository on GitHub](https://help.github.com/articles/fork-a-repo/). Then setup Travis to test your changes before you make a pull-request: You will need to [fork the fish-shell repository on GitHub](https://help.github.com/articles/fork-a-repo/), then setup Travis to test your changes before making a pull request.
1. [Sign in to Travis CI](https://travis-ci.org/auth) with your GitHub account, accepting the GitHub access permissions confirmation. 1. [Sign in to Travis CI](https://travis-ci.org/auth) with your GitHub account, accepting the GitHub access permissions confirmation.
1. Once you're signed in, and your repositories are synchronised, go to your [profile page](https://travis-ci.org/profile) and enable the fish-shell repository. 1. Once you're signed in and your repositories are synchronised, go to your [profile page](https://travis-ci.org/profile) and enable the fish-shell repository.
1. Push your changes to GitHub. 1. Push your changes to GitHub.
You'll receive an email when the tests are complete telling you whether or not any tests failed. You'll receive an email when the tests are complete telling you whether or not any tests failed.
@ -228,9 +228,9 @@ fi
exit 0 exit 0
``` ```
This will check if the push is to the master branch and, if it is, will run `make test` and only allow the push if that succeeds. In some circumstances it might be advisable to circumvent it with `git push --no-verify`, but usually that should not be necessary. This will check if the push is to the master branch and, if it is, only allow the push if running `make test` succeeds. In some circumstances it may be advisable to circumvent this check with `git push --no-verify`, but usually that isn't necessary.
To install the hook, put it in .git/hooks/pre-push and make it executable. To install the hook, place the code in a new file `.git/hooks/pre-push` and make it executable.
### Coverity Scan ### Coverity Scan
@ -240,7 +240,7 @@ We use Coverity's static analysis tool which offers free access to open source p
### Installing the Linting Tools ### Installing the Linting Tools
To install the lint checkers on Mac OS X using HomeBrew: To install the lint checkers on Mac OS X using Homebrew:
``` ```
brew tap oclint/formulae brew tap oclint/formulae
@ -248,7 +248,7 @@ brew install oclint
brew install cppcheck brew install cppcheck
``` ```
To install the lint checkers on Linux distros that use Apt: To install the lint checkers on Debian-based Linux distributions:
``` ```
sudo apt-get install clang sudo apt-get install clang
@ -258,19 +258,19 @@ sudo apt-get install cppcheck
### Installing the Reformatting Tools ### Installing the Reformatting Tools
To install the reformatting tool on Mac OS X using HomeBrew: Mac OS X:
``` ```
brew install clang-format brew install clang-format
``` ```
To install the reformatting tool on Linux distros that use Apt: Debian-based:
``` ```
apt-cache install clang-format apt-cache install clang-format
``` ```
That will list the versions available. Pick the newest one available (3.9 for Ubuntu 16.10 as I write this) and install it: Above will list all the versions available. Pick the newest one available (3.9 for Ubuntu 16.10 as I write this) and install it:
``` ```
sudo apt-get install clang-format-3.9 sudo apt-get install clang-format-3.9
@ -279,24 +279,24 @@ sudo ln -s /usr/bin/clang-format-3.9 /usr/bin/clang-format
## Message Translations ## Message Translations
Fish uses the GNU gettext library to translate messages from english to other languages. To create or update a translation run `make po/[LANGUAGE CODE].po`. Where `LANGUAGE CODE` is the two letter ISO 639-1 language code of the language you are translating to. For example, `de` for German. You'll need to have the `xgettext`, `msgfmt` and `msgmerge` commands installed to do this. Fish uses the GNU gettext library to translate messages from English to other languages. To create or update a translation run `make po/[LANGUAGE CODE].po` where `LANGUAGE CODE` is the two letter ISO 639-1 language code of the language you are translating to (e.g. `de` for German). Make sure that you have the `xgettext`, `msgfmt` and `msgmerge` commands installed in order to do this.
All messages in fish script must be enclosed in single or double quote characters. They must also be translated via a subcommand. This means that the following are not valid: All messages in fish script must be enclosed in single or double quote characters. They must also be translated via a subcommand. This means that the following are **not** valid:
``` ```
echo (_ hello) echo (_ hello)
_ "goodbye" _ "goodbye"
``` ```
Those should be written like this: Above should be written like this instead:
``` ```
echo (_ "hello") echo (_ "hello")
echo (_ "goodbye") echo (_ "goodbye")
``` ```
Note that you can use either single or double quotes to enclose the message to be translated. You can also optionally include spaces after the opening parentheses and before the closing paren. Note that you can use either single or double quotes to enclose the message to be translated. You can also optionally include spaces after the opening parentheses and once again before the closing parentheses.
Be cautious about blindly updating an existing translation file. Trivial changes to an existing message (e.g., changing the punctuation) will cause existing translations to be removed. That is because the tools do literal string matching. Which means that in general you need to carefully review any recommended deletions. Be cautious about blindly updating an existing translation file. Trivial changes to an existing message (e.g., changing the punctuation) will cause existing translations to be removed, since the tools do literal string matching. Therefore, in general, you need to carefully review any recommended deletions.
See the [wiki](https://github.com/fish-shell/fish-shell/wiki/Translations) for more details. Read the [translations wiki](https://github.com/fish-shell/fish-shell/wiki/Translations) for more information.