mirror of
https://github.com/amix/vimrc
synced 2025-06-16 09:35:01 +08:00
Updated plugins
This commit is contained in:
Amir Salihefendic
223
sources_non_forked/ale/doc/ale-development.txt
Normal file
223
sources_non_forked/ale/doc/ale-development.txt
Normal file
@ -0,0 +1,223 @@
|
||||
*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:
|
||||
Reference in New Issue
Block a user