Close #1685 - Move developer documentation to a help file

1 files changed, 169 insertions, 1 deletions

diff --git a/doc/ale-development.txt b/doc/ale-development.txt
index 9b718ac2..bcbe2c7f 100644
--- a/doc/ale-development.txt
+++ b/doc/ale-development.txt
@@ -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
@@ -52,4 +61,163 @@ 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: