github-mirror/fish-shell
2
0
Fork 0
mirror of https://github.com/fish-shell/fish-shell.git synced 2024-11-25 09:39:52 +08:00
Code Issues Actions 2 Packages Projects Releases Wiki Activity

CONTRIBUTING: Simplify a bit

Browse Source 
Add a "General" section and a short summary at the beginning.

[ci skip]
This commit is contained in:
Fabian Homborg 2020-11-22 14:35:56 +01:00
parent 47ddb6d516
commit e30f661867
1 changed files with 60 additions and 53 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

113
CONTRIBUTING.rst
View File

@ -3,60 +3,29 @@ Guidelines For Developers
This document provides guidelines for making changes to the fish-shell This document provides guidelines for making changes to the fish-shell
project. This includes rules for how to format the code, naming project. This includes rules for how to format the code, naming
conventions, et cetera. Generally known as the style of the code. conventions, et cetera.
See the bottom of this document for help on installing the linting and In short:
style reformatting tools discussed in the following sections.
Fish source should limit the C++ features it uses to those available in - Be conservative in what you need (``C++11``, few dependencies)
C++11. It should not use exceptions. - Use automated tools to help you (including ``make test``, ``build_tools/style.fish`` and ``make lint``)
Before introducing a new dependency, please make it optional with General
graceful failure if possible. Add any new dependencies to the README.rst -------
under the *Running* and/or *Building* sections.
Versioning Fish uses C++11. Newer C++ features should not be used to make it possible to use on older systems.
----------
The fish version is constructed by the *build_tools/git_version_gen.sh* It does not use exceptions, they are disabled at build time with ``-fno-exceptions``.
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 Don't introduce new dependencies unless absolutely necessary, and if you do,
-------------------- please make it optional with graceful failure if possible.
Add any new dependencies to the README.rst under the *Running* and/or *Building* sections.
You should not depend on symbols being visible to a ``*.cpp`` module This also goes for completion scripts and functions - if at all possible, they should only use
from ``#include`` statements inside another header file. In other words POSIX-compatible invocations of any tools, and no superfluous dependencies.
if your module does ``#include "common.h"`` and that header does
``#include "signal.h"`` your module should not assume the sub-include is
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``) E.g. some completions deal with JSON data. In those it's preferable to use python to handle it,
command will run the as opposed to ``jq``, because fish already optionally uses python elsewhere. (It also happens to be quite a bit *faster*)
`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
Lint Free Code Lint Free Code
-------------- --------------
@ -66,10 +35,6 @@ potential bugs or code that is extremely hard to understand. They also
help ensure the code has a consistent style and that it avoids patterns help ensure the code has a consistent style and that it avoids patterns
that tend to confuse people. that tend to confuse people.
Ultimately we want lint free code. However, at the moment a lot of
cleanup is required to reach that goal. For now simply try to avoid
introducing new lint.
To make linting the code easy there are two make targets: ``lint`` and To make linting the code easy there are two make targets: ``lint`` and
``lint-all``. The latter does exactly what the name implies. The former ``lint-all``. The latter does exactly what the name implies. The former
will lint any modified but not committed ``*.cpp`` files. If there is no will lint any modified but not committed ``*.cpp`` files. If there is no
@ -80,9 +45,6 @@ help catch mistakes such as using ``wcwidth()`` rather than
``fish_wcwidth()``. Please add a new rule if you find similar mistakes ``fish_wcwidth()``. Please add a new rule if you find similar mistakes
being made. being made.
Fish also depends on ``diff`` and `pexpect
<https://pexpect.readthedocs.io/en/stable/>`__ for its tests.
Dealing With Lint Warnings Dealing With Lint Warnings
~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~
@ -310,6 +272,8 @@ 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 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.
Fish also depends on ``diff`` and `pexpect
<https://pexpect.readthedocs.io/en/stable/>`__ for its tests.
Local testing Local testing
~~~~~~~~~~~~~ ~~~~~~~~~~~~~
@ -486,3 +450,46 @@ recommended deletions.
Read the `translations Read the `translations
wiki <https://github.com/fish-shell/fish-shell/wiki/Translations>`__ for wiki <https://github.com/fish-shell/fish-shell/wiki/Translations>`__ for
more information. 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 "signal.h"`` your module should not assume the sub-include is
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 <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