mirror of
https://github.com/fish-shell/fish-shell
synced 2024-12-26 04:43:10 +00:00
CONTRIBUTING: Rationalize sections
Mostly this tries to give logical header levels, so the "Fish Style Guide" section is in the "Code Style" section Also remove a few unimportant C++-centric sections - I'm not sure iwyu even runs anymore, and cppcheck isn't great in my experience.
This commit is contained in:
Fabian Boehm
parent
272d123431
commit
756cb15f81
1 changed files with 34 additions and 99 deletions
133
CONTRIBUTING.rst
133
CONTRIBUTING.rst
|
|
@ -1,3 +1,4 @@
|
|||
####################
|
||||
Contributing To Fish
|
||||
####################
|
||||
|
||||
|
|
@ -11,7 +12,7 @@ Whether you want to change some of the core rust/C++ source, enhance or add a co
|
|||
improve the documentation or translate something, this document will tell you how.
|
||||
|
||||
Getting Set Up
|
||||
--------------
|
||||
==============
|
||||
|
||||
Fish is developed on Github, at https://github.com/fish-shell/fish-shell.
|
||||
|
||||
|
|
@ -37,7 +38,7 @@ Of course not everything is required always - if you just want to contribute som
|
|||
and if the change is very simple and obvious you can just send it in. Use your judgement!
|
||||
|
||||
Guidelines
|
||||
----------
|
||||
==========
|
||||
|
||||
In short:
|
||||
|
||||
|
|
@ -45,7 +46,7 @@ In short:
|
|||
- Use automated tools to help you (including ``make test``, ``build_tools/style.fish`` and ``make lint``)
|
||||
|
||||
Contributing completions
|
||||
------------------------
|
||||
========================
|
||||
|
||||
Completion scripts are the most common contribution to fish, and they are very welcome.
|
||||
|
||||
|
|
@ -77,7 +78,7 @@ Put your completion script into share/completions/name-of-command.fish. If you h
|
|||
If you want to add tests, you probably want to add a littlecheck test. See below for details.
|
||||
|
||||
Contributing documentation
|
||||
--------------------------
|
||||
==========================
|
||||
|
||||
The documentation is stored in ``doc_src/``, and written in ReStructured Text and built with Sphinx.
|
||||
|
||||
|
|
@ -90,7 +91,7 @@ which will build the docs as html in /tmp/fish-doc. You can open it in a browser
|
|||
The builtins and various functions shipped with fish are documented in doc_src/cmds/.
|
||||
|
||||
Contributing to fish's Rust/C++ core
|
||||
------------------------------------
|
||||
====================================
|
||||
|
||||
As of now, fish is in the process of switching from C++11 to Rust, so this is in flux.
|
||||
|
||||
|
|
@ -100,7 +101,6 @@ Importantly, the initial port strives for fidelity with the existing C++ codebas
|
|||
so it won't be 100% idiomatic rust - in some cases it'll have some awkward interface code
|
||||
in order to interact with the C++.
|
||||
|
||||
|
||||
Linters
|
||||
-------
|
||||
|
||||
|
|
@ -118,8 +118,10 @@ help catch mistakes such as using ``wcwidth()`` rather than
|
|||
``fish_wcwidth()``. Please add a new rule if you find similar mistakes
|
||||
being made.
|
||||
|
||||
We use ``clippy`` for Rust.
|
||||
|
||||
Code Style
|
||||
----------
|
||||
==========
|
||||
|
||||
To ensure your changes conform to the style rules run
|
||||
|
||||
|
|
@ -149,6 +151,20 @@ If you want to check the style of the entire code base run
|
|||
That command will refuse to restyle any files if you have uncommitted
|
||||
changes.
|
||||
|
||||
Fish Script Style Guide
|
||||
-----------------------
|
||||
|
||||
1. All fish scripts, such as those in the *share/functions* and *tests*
|
||||
directories, should be formatted using the ``fish_indent`` command.
|
||||
|
||||
2. 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.
|
||||
|
||||
3. 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.
|
||||
|
||||
Configuring Your Editor for Fish Scripts
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
|
|
@ -185,20 +201,6 @@ made to run fish_indent via e.g.
|
|||
(add-hook 'fish-mode-hook (lambda ()
|
||||
(add-hook 'before-save-hook 'fish_indent-before-save)))
|
||||
|
||||
Fish Script Style Guide
|
||||
-----------------------
|
||||
|
||||
1. All fish scripts, such as those in the *share/functions* and *tests*
|
||||
directories, should be formatted using the ``fish_indent`` command.
|
||||
|
||||
2. 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.
|
||||
|
||||
3. 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
|
||||
---------------
|
||||
|
||||
|
|
@ -248,7 +250,7 @@ Rust Style Guide
|
|||
Use ``cargo fmt`` and ``cargo clippy``. Clippy warnings can be turned off if there's a good reason to.
|
||||
|
||||
Testing
|
||||
-------
|
||||
=======
|
||||
|
||||
The source code for fish includes a large collection of tests. If you
|
||||
are making any changes to fish, running these tests is a good way to make
|
||||
|
|
@ -273,7 +275,7 @@ fish_tests.cpp is mostly useful for unit tests - if you wish to test that a func
|
|||
The pexpects are written in python and can simulate input and output to/from a terminal, so they are needed for anything that needs actual interactivity. The runner is in build_tools/pexpect_helper.py, in case you need to modify something there.
|
||||
|
||||
Local testing
|
||||
~~~~~~~~~~~~~
|
||||
-------------
|
||||
|
||||
The tests can be run on your local computer on all operating systems.
|
||||
|
||||
|
|
@ -283,7 +285,7 @@ The tests can be run on your local computer on all operating systems.
|
|||
make test
|
||||
|
||||
Git hooks
|
||||
~~~~~~~~~
|
||||
---------
|
||||
|
||||
Since developers sometimes forget to run the tests, it can be helpful to
|
||||
use git hooks (see githooks(5)) to automate it.
|
||||
|
|
@ -326,7 +328,7 @@ To install the hook, place the code in a new file
|
|||
``.git/hooks/pre-push`` and make it executable.
|
||||
|
||||
Coverity Scan
|
||||
~~~~~~~~~~~~~
|
||||
-------------
|
||||
|
||||
We use Coverity’s static analysis tool which offers free access to open
|
||||
source projects. While access to the tool itself is restricted,
|
||||
|
|
@ -336,42 +338,8 @@ with their GitHub account. Currently, tests are triggered upon merging
|
|||
the ``master`` branch into ``coverity_scan_master``. Even if you are not
|
||||
a fish developer, you can keep an eye on our statistics there.
|
||||
|
||||
Installing the Required Tools
|
||||
-----------------------------
|
||||
|
||||
Installing the Linting Tools
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
To install the lint checkers on Mac OS X using Homebrew:
|
||||
|
||||
::
|
||||
|
||||
brew install cppcheck
|
||||
|
||||
To install the lint checkers on Debian-based Linux distributions:
|
||||
|
||||
::
|
||||
|
||||
sudo apt-get install clang
|
||||
sudo apt-get install cppcheck
|
||||
|
||||
Installing the Formatting Tools
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Mac OS X:
|
||||
|
||||
::
|
||||
|
||||
brew install clang-format
|
||||
|
||||
Debian-based:
|
||||
|
||||
::
|
||||
|
||||
sudo apt-get install clang-format
|
||||
|
||||
Message Translations
|
||||
--------------------
|
||||
Contributing Translations
|
||||
=========================
|
||||
|
||||
Fish uses the GNU gettext library to translate messages from English to
|
||||
other languages.
|
||||
|
|
@ -385,7 +353,8 @@ macro:
|
|||
streams.out.append_format(_(L"%ls: There are no jobs\n"), argv[0]);
|
||||
|
||||
All messages in fish script must be enclosed in single or double quote
|
||||
characters. They must also be translated via a subcommand. This means
|
||||
characters for the message extraction to find them.
|
||||
They must also be translated via a command substitution. This means
|
||||
that the following are **not** valid:
|
||||
|
||||
::
|
||||
|
|
@ -400,9 +369,9 @@ Above should be written like this instead:
|
|||
echo (_ "hello")
|
||||
echo (_ "goodbye")
|
||||
|
||||
Note that you can use either single or double quotes to enclose the
|
||||
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.
|
||||
the opening parentheses or before the closing parentheses.
|
||||
|
||||
Creating and updating translations requires the Gettext tools, including
|
||||
``xgettext``, ``msgfmt`` and ``msgmerge``. Translation sources are
|
||||
|
|
@ -438,44 +407,10 @@ wiki <https://github.com/fish-shell/fish-shell/wiki/Translations>`__ for
|
|||
more information.
|
||||
|
||||
Versioning
|
||||
----------
|
||||
==========
|
||||
|
||||
The fish version is constructed by the *build_tools/git_version_gen.sh*
|
||||
script. For developers the version is the branch name plus the output of
|
||||
``git describe --always --dirty``. Normally the main part of the version
|
||||
will be the closest annotated tag. Which itself is usually the most
|
||||
recent release number (e.g., ``2.6.0``).
|
||||
|
||||
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 "signals.h"`` your module should not assume the sub-include is
|
||||
present. It should instead directly ``#include "signals.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 <https://include-what-you-use.org/>`__ tool. You
|
||||
can find the IWYU project 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 ``apt-get``:
|
||||
|
||||
::
|
||||
|
||||
sudo apt-get install iwyu
|
||||
|
|
|
|||
Loading…
Reference in a new issue