mirror of https://github.com/dense-analysis/ale
224 lines
10 KiB
Plaintext
224 lines
10 KiB
Plaintext
*ale-development.txt* For Vim version 8.0.
|
|
*ale-development*
|
|
|
|
ALE Development Documentation
|
|
|
|
===============================================================================
|
|
CONTENTS *ale-development-contents*
|
|
|
|
1. Introduction.........................|ale-development-introduction|
|
|
2. Design Goals.........................|ale-design-goals|
|
|
3. Coding Standards.....................|ale-coding-standards|
|
|
4. Testing ALE..........................|ale-development-tests|
|
|
|
|
===============================================================================
|
|
1. Introduction *ale-development-introduction*
|
|
|
|
This document contains helpful information for ALE developers, including
|
|
design goals, information on how to run the tests, coding standards, and so
|
|
on. You should read this document if you want to get involved with ALE
|
|
development.
|
|
|
|
===============================================================================
|
|
2. Design Goals *ale-design-goals*
|
|
|
|
This section lists design goals for ALE, in no particular order. They are as
|
|
follows.
|
|
|
|
ALE code should be almost 100% VimL. This makes the plugin as portable as
|
|
possible.
|
|
|
|
ALE should run without needing any other plugins to be installed, to make
|
|
installation simple. ALE can integrate with other plugins for more advanced
|
|
functionality, non-essential functionality, or improving on basic first party
|
|
functionality.
|
|
|
|
ALE should check files with as many tools as possible by default, except where
|
|
they cause security issues or make excessive use of resources on modern
|
|
machines.
|
|
|
|
ALE should be free of breaking changes to the public API, which is comprised of
|
|
documented functions and options, until a major version is planned. Breaking
|
|
changes should be preceded by a deprecation phase complete with warnings.
|
|
Changes required for security may be an exception.
|
|
|
|
ALE supports Vim 8 and above, and NeoVim 0.2.0 or newer. These are the
|
|
earliest versions of Vim and NeoVim which support |job|, |timer|, |closure|,
|
|
and |lambda| features. All ALE code should be written so it is compatible with
|
|
these versions of Vim, or with version checks so particular features can
|
|
degrade or fail gracefully.
|
|
|
|
Just about everything should be documented and covered with tests.
|
|
|
|
By and large, people shouldn't pay for the functionality they don't use. Care
|
|
should be taken when adding new features, so supporting new features doesn't
|
|
degrade the general performance of anything ALE does.
|
|
|
|
LSP support will become more important as time goes on. ALE should provide
|
|
better support for LSP features as time goes on.
|
|
|
|
When merging pull requests, you should respond with `Cheers! :beers:`, purely
|
|
for comedy value.
|
|
|
|
===============================================================================
|
|
3. Coding Standards *ale-coding-standards*
|
|
|
|
The following general coding standards should be adhered to for Vim code.
|
|
|
|
* Check your Vim code with `Vint` and do everything it says. ALE will check
|
|
your Vim code with Vint automatically. See: https://github.com/Kuniwak/vint
|
|
Read ALE's `Dockerfile` to see which version of `Vint` it uses.
|
|
* Try to write descriptive and concise names for variables and functions.
|
|
Names shouldn't be too short or too long. Think about others reading your
|
|
code later on.
|
|
* Use `snake_case` names for variables and arguments, and `PascalCase` names
|
|
for functions. Prefix every variable name with its scope. (`l:`, `g:`, etc.)
|
|
* Try to keep lines no longer than 80 characters, but this isn't an absolute
|
|
requirement.
|
|
* Use 4 spaces for every level of indentation in Vim code.
|
|
* Add a blank line before every `function`, `if`, `for`, `while`, or `return`,
|
|
which doesn't start a new level of indentation. This makes the logic in
|
|
your code easier to follow.
|
|
* End every file with a trailing newline character, but not with extra blank
|
|
lines. Remove trailing whitespace from the ends of lines.
|
|
* Write the full names of commands instead of abbreviations. For example, write
|
|
`function` instead of `func`, and `endif` instead of `end`.
|
|
* Write functions with `!`, so files can be reloaded. Use the |abort| keyword
|
|
for all functions, so functions exit on the first error.
|
|
* Make sure to credit yourself in files you have authored with `Author:`
|
|
and `Description:` comments.
|
|
|
|
In addition to the above general guidelines for the style of your code, you
|
|
should also follow some additional rules designed to prevent mistakes. Some of
|
|
these are reported with ALE's `custom-linting-rules` script. See
|
|
|ale-development-tests|.
|
|
|
|
* Don't leave stray `:echo` lines in code. Use `execute 'echo' ...` if you must
|
|
echo something.
|
|
* For strings use |is#| instead of |==#|, `is?` instead of `==?`, `isnot#`
|
|
instead of `!=#`, and `isnot?` instead of `!=?`. This is because `'x' ==# 0`
|
|
returns 1, while `'x' is# 0` returns 0, so you will experience fewer issues
|
|
when numbers are compared with strings. `is` and `isnot` also do not throw
|
|
errors when other objects like List or Dictionaries are compared with
|
|
strings.
|
|
* Don't use the `getcwd()` function in the ALE codebase. Most of ALE's code
|
|
runs from asynchronous callback functions, and these functions can execute
|
|
from essentially random buffers. Therefore, the `getcwd()` output is
|
|
useless. Use `expand('#' . a:buffer . ':p:h')` instead. Don't use
|
|
`expand('%...')` for the same reason.
|
|
* Don't use the `simplify()` function. It doesn't simplify paths enough. Use
|
|
`ale#path#Simplify()` instead.
|
|
* Don't use the `shellescape()` function. It doesn't escape arguments properly
|
|
on Windows. Use `ale#Escape()` instead, which will avoid escaping where it
|
|
isn't needed, and generally escape arguments better on Windows.
|
|
|
|
Apply the following guidelines when writing Vader test files.
|
|
|
|
* Use 2 spaces for Vader test files, instead of the 4 spaces for Vim files.
|
|
* If you write `Before` and `After` blocks, you should typically write them at
|
|
the top of the file, so they run for all tests. There may be some tests
|
|
where it make sense to modify the `Before` and `After` code part of the way
|
|
through the file.
|
|
* If you modify any settings or global variables, reset them in `After`
|
|
blocks. The Vader `Save` and `Restore` commands can be useful for this
|
|
purpose.
|
|
* If you load or define linters in tests, write `call ale#linter#Reset()` in
|
|
an `After` block.
|
|
* Just write `Execute` blocks for Vader tests, and don't bother writing `Then`
|
|
blocks. `Then` blocks execute after `After` blocks in older versions, and
|
|
that can be confusing.
|
|
|
|
Apply the following rules when writing Bash scripts.
|
|
|
|
* Run `shellcheck`, and do everything it says.
|
|
See: https://github.com/koalaman/shellcheck
|
|
* Try to write scripts so they will run on Linux, BSD, or Mac OSX.
|
|
|
|
===============================================================================
|
|
4. Testing ALE *ale-development-tests*
|
|
|
|
ALE is tested with a suite of tests executed in Travis CI and AppVeyor. ALE
|
|
runs tests with the following versions of Vim in the following environments.
|
|
|
|
1. Vim 8.0.0027 on Linux via Travis CI.
|
|
2. NeoVim 0.2.0 on Linux via Travis CI.
|
|
3. NeoVim 0.3.0 on Linux via Travis CI.
|
|
4. Vim 8 (stable builds) on Windows via AppVeyor.
|
|
|
|
If you are developing ALE code on Linux, Mac OSX, or BSD, you can run ALEs
|
|
tests by installing Docker and running the `run-tests` script. Follow the
|
|
instructions on the Docker site for installing Docker.
|
|
See: https://docs.docker.com/install/
|
|
|
|
NOTE: Don't forget to add your user to the `docker` group on Linux, or Docker
|
|
just won't work. See: https://docs.docker.com/install/linux/linux-postinstall/
|
|
|
|
If you run simply `./run-tests` from the ALE repository root directory, the
|
|
latest Docker image for tests will be downloaded if needed, and the script
|
|
will run all of the tests in Vader, Vint checks, and several Bash scripts for
|
|
finding extra issues. Run `./run-tests --help` to see all of the options the
|
|
script supports. Note that the script supports selecting particular test files.
|
|
|
|
Generally write tests for any changes you make. The following types of tests
|
|
are recommended for the following types of code.
|
|
|
|
* New/edited error handler callbacks -> Write tests in `test/handler`
|
|
* New/edited command callbacks -> Write tests in `test/command_callback`
|
|
* New/edited fixer functions -> Write tests in `test/fixers`
|
|
|
|
Look at existing tests in the codebase for examples of how to write tests.
|
|
Refer to the Vader documentation for general information on how to write Vader
|
|
tests: https://github.com/junegunn/vader.vim
|
|
|
|
When you add new linters or fixers, make sure to add them into the table in
|
|
the README, and also into the |ale-support| list in the main help file. If you
|
|
forget to keep them both in sync, you should see an error like the following
|
|
in Travis CI. >
|
|
|
|
========================================
|
|
diff README.md and doc/ale.txt tables
|
|
========================================
|
|
Differences follow:
|
|
|
|
--- /tmp/readme.qLjNhJdB 2018-07-01 16:29:55.590331972 +0100
|
|
+++ /tmp/doc.dAi8zfVE 2018-07-01 16:29:55.582331877 +0100
|
|
@@ -1 +1 @@
|
|
- ASM: gcc, foobar
|
|
+ ASM: gcc
|
|
<
|
|
Make sure to list documentation entries for linters and fixers in individual
|
|
help files in the table of contents, and to align help tags to the right
|
|
margin. For example, if you add a heading for an `aardvark` tool to
|
|
`ale-python.txt` with a badly aligned doc tag, you will see errors like so. >
|
|
|
|
========================================
|
|
Look for badly aligned doc tags
|
|
========================================
|
|
Badly aligned tags follow:
|
|
|
|
doc/ale-python.txt:aardvark ...
|
|
========================================
|
|
Look for table of contents issues
|
|
========================================
|
|
|
|
Check for bad ToC sorting:
|
|
|
|
Check for mismatched ToC and headings:
|
|
|
|
--- /tmp/table-of-contents.mwCFOgSI 2018-07-01 16:33:25.068811878 +0100
|
|
+++ /tmp/headings.L4WU0hsO 2018-07-01 16:33:25.076811973 +0100
|
|
@@ -168,6 +168,7 @@
|
|
pyrex (cython), ale-pyrex-options
|
|
cython, ale-pyrex-cython
|
|
python, ale-python-options
|
|
+ aardvark, ale-python-aardvark
|
|
autopep8, ale-python-autopep8
|
|
black, ale-python-black
|
|
flake8, ale-python-flake8
|
|
<
|
|
Make sure to make the table of contents match the headings, and to keep the
|
|
doc tags on the right margin.
|
|
|
|
===============================================================================
|
|
vim:tw=78:ts=2:sts=2:sw=2:ft=help:norl:
|