marc/ale
Archived
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Close #1685 - Move developer documentation to a help file

Browse source
This commit is contained in:
w0rp 2018-07-01 19:56:17 +01:00
parent d456ac19ca
commit 2a78401066
No known key found for this signature in database
GPG key ID: 0FC1ECAA8C81CD83
4 changed files with 197 additions and 176 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

156
CONTRIBUTING.md
View file

@ -1,37 +1,11 @@
# Contributing to ALE
1. [Guidelines](#guidelines)
2. [Creating Issues](#issues)
3. [Creating Pull Requests](#pull-requests)
1. [Adding a New Linter](#adding-a-new-linter)
2. [Adding New Options](#adding-new-options)
4. [Writing Documentation](#writing-documentation)
1. [Documenting New Linters](#documenting-new-linters)
2. [Editing the Online Documentation](#editing-online-documentation)
3. [Documenting Linter Options](#documenting-linter-options)
5. [In Case of Busses](#in-case-of-busses)
<a name="guidelines"></a>
## 1. Guidelines
## Guidelines
Have fun, and work on whatever floats your boat. Take It Easy :tm:.
Don't forget to **write documentation** for whatever it is you are doing.
See the ["Writing Documentation"](#writing-documentation) section.
For help with contributing to ALE, see `:help ale-development` in Vim, or view
the help file online [here](/w0rp/ale/blob/master/doc/ale-development.txt).
Remember to write Vader tests for most of the code you write. You can look at
existing Vader tests in the `test` directory for examples.
When writing code, follow the [Google Vimscript Style
Guide](https://google.github.io/styleguide/vimscriptguide.xml), and run `vint
-s` on your files to check for most of what the guide mentions and more. If you
install this plugin (ALE) and install [Vint](https://github.com/Kuniwak/vint), it
will check your code while you type.
<a name="issues"></a>
## 2. Creating Issues
## Creating Issues
Before creating any issues, please look through the current list of issues and
pull requests, and ensure that the issue hasn't already been reported. If an
@ -49,125 +23,3 @@ operating system, or any other information you think might be helpful.
Please describe your issue in clear, grammatically correct, and easy to
understand English. You are more likely to see an issue resolved if others
can understand you.
<a name="pull-requests"></a>
## 3. Creating Pull Requests
For code you write, make sure to credit yourself at the top of files you add,
and probably those you modify. You can write some comments at the top of your
VIM files.
```vim
" Author: John Smith <john.smith@gmail.com>
" Description: This file adds support for awesomelinter for the best language ever.
```
If you want to credit multiple authors, you can comma separate them.
```vim
" Author: John Smith <john.smith@gmail.com>, Jane Doe <https://jane-doe.info>
```
<a name="adding-a-new-linter"></a>
### 3.i. Adding a New Linter
If you add a new linter, look for existing handlers first in the
[handlers](autoload/ale/handlers) directory. One of the handlers there may
already be able to handle your lines of output. If you find that your new
linter replicates an existing error handler, consider pulling it up into the
[handlers](autoload/ale/handlers) directory, and use the generic handler in
both places.
When you add a linter, make sure the language for the linter and the linter
itself are present in the table in the [README.md](README.md) file and in the
Vim [help file](doc/ale.txt). The programs and linters should be sorted
alphabetically in the table and list.
<a name="adding-new-options"></a>
### 3.ii. Adding New Options
If you add new options to the plugin, make sure to document those new options
in the [README.md](README.md) file, and also in the [help file](doc/ale.txt).
Follow the format of other options in each. Global options should appear in the
README file, and in the relevant section in the help file. Options specific
to a particular linter should appear in the section for that linter.
Linter options for customizing general argument lists should be named
`g:ale_<filetype>_<linter>_options`, so that all linters can have similar
global variable names.
Any options for linters should be set to some default value so it is always
easy to see what the default is with `:echo g:ale...`.
<a name="writing-documentation"></a>
## 4. Writing Documentation
If you are adding new linters, changing the API, adding new options, etc., you
_must_ write some documentation describing it in the `doc/ale.txt` file. New
linters _must_ be added to the `README.md` file too, so other users can get a
quick overview of the supported tools.
<a name="documenting-new-linters"></a>
### 4.i Documenting New Linters
If you add a new linter to the project, edit the table in the `README.md` file,
and edit the list of linters at the top of the `doc/ale.txt` file. The linters
should be sorted vertically in lexicographic (alphabetical) order by the
programming language name or filetype, and the tools for each language should
be sorted in lexicographic order horizontally. Sorting in this manner is a fair
manner of presenting all of the information in an easy to scan way, without
giving some unfair preference to any particular tool or language.
<a name="editing-online-documentation"></a>
### 4.ii Editing the Online Documentation
The "online documentation" file used for this project lives in `doc/ale.txt`.
This is the file used for generating `:help` text inside Vim itself. There are
some guidelines to follow for this file.
1. Keep all text within a column size of 79 characters, inclusive.
2. Open a section with 79 `=` or `-` characters, for headings and subheadings.
3. Sections should have a _single_ blank line before or after.
4. Between descriptions of variables/functions/commands, use _two_ blank lines.
5. Up-indent the description of a variable/function/command by two spaces.
6. Place tags at the ends of lines, with the final characters on column 79.
All of the tags should line up perfectly on the same column as you scan
down through the document.
7. Keep the table of contents balanced so the longest tag link ends on column
79, and so all links line up perfectly on their first character, on the
left.
<a name="documenting-linter-options"></a>
### 4.iii Documenting Linter Options
For documenting new linter options, please add a new sub-section under the
"Linter Specific Options" section describing all of the global options added
for each linter, and what the default values of the options are. All global
options for linters should be set to some default value. This will allow users
to look up the default value easily by typing `:echo g:ale_...`.
<a name="in-case-of-busses"></a>
## 5. In Case of Busses
Should the principal author of the ALE project and all collaborators with the
required access needed to properly administrate the project on GitHub or any
other website either perish or disappear, whether by tragic traffic accident
or government abduction, etc., action should be taken to ensure that the
project continues. If no one is left to administer the project where it is
hosted, please fork the project and nominate someone capable to administer it.
Preferably, in such an event, a single fork of the project will replace the
original, and life will go on, except the life of whoever vanished, because
then they will probably be dead.
Should w0rp suddenly disappear, then he was probably killed in a traffic
accident, or the government finally decided to kill him and make it look like
suicide. In the latter event, please subvert said government and restore
order to the universe, and ensure peace for mankind.

22
PULL_REQUEST_TEMPLATE.md
View file

@ -1,22 +1,8 @@
<!--
READ THIS: Before creating a pull request, please consider the following first.
Before creating a pull request, do the following.
* The most important thing you can do is write tests. Code without tests
probably doesn't work, and will almost certainly stop working later on. Pull
requests without tests probably won't be accepted, although there are some
exceptions.
* Read the Contributing guide linked above first.
* If you are adding a new linter, remember to update the README.md file and
doc/ale.txt first.
* If you add or modify a function for converting error lines into loclist items
that ALE can work with, please add Vader tests for them. Look at existing
tests in the test/handler directory, etc.
* If you add or modify a function for computing a command line string for
running a command, please add Vader tests for that. Look at existing
tests in the test/command_callback directory, etc.
* Generally try and cover anything with Vader tests, although some things just
can't be tested with Vader, or at least they can be hard to test. Consider
breaking up your code so that some parts can be tested, and generally open up
a discussion about it.
* Have fun!
* Read the documentation that comes with ALE with `:help ale-development`.
Have fun!
-->

170
doc/ale-development.txt
View file

@ -8,6 +8,8 @@ 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*
@ -20,7 +22,8 @@ development.
===============================================================================
2. Design Goals *ale-design-goals*
This section lists design goals for ALE, in no particular order.
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.
@ -39,6 +42,12 @@ 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
@ -51,5 +60,164 @@ 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 *ale-python-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:

25
run-tests
View file

@ -5,12 +5,9 @@ set -u
# Author: w0rp <devw0rp@gmail.com>
#
# This script runs tests for the ALE project. The following options are
# accepted:
# This script runs tests for the ALE project. Run `./run-tests --help` for
# options, or read the output below.
#
# -v Enable verbose output
# --neovim-only Run tests only for NeoVim
# --vim-only Run tests only for Vim
image=w0rp/ale
current_image_id=13b990377be9
@ -68,6 +65,24 @@ while [ $# -ne 0 ]; do
run_neovim_03_tests=0
shift
;;
--help)
echo 'Usage: ./run-tests [OPTION]... [FILE]...'
echo
echo 'Filenames can be given as arguments to run a subset of tests.'
echo 'For example: ./run-tests test/test_ale_var.vader'
echo
echo 'Options:'
echo ' -v Enable verbose output'
echo ' -q Hide output for successful tests'
echo ' --neovim-only Run tests only for NeoVim 0.2 and 0.3'
echo ' --neovim-02-only Run tests only for NeoVim 0.2'
echo ' --neovim-03-only Run tests only for NeoVim 0.3'
echo ' --vim-only Run tests only for Vim'
echo ' --linters-only Run only Vint and custom checks'
echo ' --help Show this help text'
echo ' -- Stop parsing options after this'
exit 0
;;
--)
shift
break