From 756cb15f812596dbedbd421c955f505c84a0bfec Mon Sep 17 00:00:00 2001 From: Fabian Boehm Date: Fri, 2 Jun 2023 17:26:35 +0200 Subject: [PATCH] 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. --- CONTRIBUTING.rst | 133 ++++++++++++----------------------------------- 1 file changed, 34 insertions(+), 99 deletions(-) diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 6a5a9ccad..e77345c55 100644 --- a/CONTRIBUTING.rst +++ b/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 `__ 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 `__ tool. You -can find the IWYU project on -`github `__. - -To install the tool on OS X you’ll need to add a -`formula `__ then install -it: - -:: - - brew tap jasonmp85/iwyu - brew install iwyu - -On Ubuntu you can install it via ``apt-get``: - -:: - - sudo apt-get install iwyu