*ale-development.txt* For Vim version 8.0. *ale-dev* *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| 4.1. Writing Linter Tests.............|ale-development-linter-tests| 4.2. Writing Fixer Tests..............|ale-development-fixer-tests| 4.3. Running Tests in a Windows VM....|ale-development-windows-tests| 5. Contributing.........................|ale-development-contributing| 5.1. Preparing a Release..............|ale-development-release| =============================================================================== 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.6.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. Write `" no-custom-checks` above the line 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. * Don't use the `tempname()` function. It doesn't work when `$TMPDIR` isn't set. Use `ale#util#Tempname()` instead, which temporarily sets `$TMPDIR` appropriately where needed. * Use `snake_case` names for linter names, so they can be used as part of variable names. You can define `aliases` for linters, for other names people might try to configure linters with. * Use |v:t_TYPE| variables instead of `type()`, which are more readable. 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-dev-tests* *ale-tests* ALE is tested with a suite of tests executed via GitHub Actions and AppVeyor. ALE runs tests with the following versions of Vim in the following environments. 1. Vim 8.0.0027 on Linux via GitHub Actions. 2. Vim 9.0.0297 on Linux via GitHub Actions. 3. NeoVim 0.6.0 on Linux via GitHub Actions. 4. NeoVim 0.8.0 on Linux via GitHub Actions. 6. 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. Once you get used to dealing with Vim and NeoVim compatibility issues, you probably want to use `./run-tests --fast -q` for running tests with only the fastest available Vim version, and with success messages from tests suppressed. 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 linter definition -> Write tests in `test/linter` * 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 If you need to add any supporting files for tests, such as empty files present to test searching upwards through paths for configuration files, they can be added to the `test/test-files` directory. See |ale-development-linter-tests| for more information on how to write linter tests. When you add new linters or fixers, make sure to add them into the tables in supported-tools.md and |ale-supported-languages-and-tools.txt|. If you forget to keep them both in sync, you should see an error like the following in the builds run for GitHub Actions. > ======================================== diff supported-tools.md and doc/ale-supported-languages-and-tools.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. =============================================================================== 4.1 Writing Linter Tests *ale-development-linter-tests* Tests for ALE linters take two forms. 1. Tests for handling the output of commands. 2. Tests for checking which commands are run, or connections are made. Tests of the first form should go in the `test/handler` directory, and should be written like so. > Before: " Load the file which defines the linter. runtime ale_linters/filetype/linter_name_here.vim After: " Unload all linters again. call ale#linter#Reset() Execute(The output should be correct): " Test that the right loclist items are parsed from the handler. AssertEqual \ [ \ { \ 'lnum': 1, \ 'type': 'E', \ 'text': 'Something went wrong', \ }, \ ], \ ale_linters#filetype#linter_name#Handle(bufnr(''), [ \ '1:Something went wrong', \ ] < Tests for what ALE runs should go in the `test/linter` directory, and should be written like so. > Before: " Load the linter and set up a series of commands, reset linter variables, " clear caches, etc. " " Vader's 'Save' command will be called here for linter variables. call ale#assert#SetUpLinterTest('filetype', 'linter_name') After: " Reset linters, variables, etc. " " Vader's 'Restore' command will be called here. call ale#assert#TearDownLinterTest() Execute(The default command should be correct): " AssertLinter checks the executable and command. " Pass expected_executable, expected_command AssertLinter 'some-command', ale#Escape('some-command') . ' --foo' Execute(Check chained commands): " GivenCommandOutput can be called with 1 or more list for passing output " to chained commands. The output for each callback defaults to an empty " list. GivenCommandOutput ['v2.1.2'] " Given a List of commands, check all of them. " Given a String, only the last command in the chain will be checked. AssertLinter 'some-command', [ \ ale#Escape('some-command') . ' --version', \ ale#Escape('some-command') . ' --foo', \] < The full list of commands that will be temporarily defined for linter tests given the above setup are as follows. `GivenCommandOutput [...]` - Define output for ale#command#Run. `AssertLinterCwd cwd` - Check the `cwd` for the linter. `AssertLinter executable, command` - Check the executable and command. `AssertLinterNotExecuted` - Check that linters will not be executed. `AssertLSPLanguage language` - Check the language given to an LSP server. `AssertLSPOptions options_dict` - Check the options given to an LSP server. `AssertLSPConfig config_dict` - Check the config given to an LSP server. `AssertLSPProject project_root` - Check the root given to an LSP server. `AssertLSPAddress address` - Check the address to an LSP server. =============================================================================== 4.2 Writing Fixer Tests *ale-development-fixer-tests* Tests for ALE fixers should go in the `test/fixers` directory, and should be written like so. > Before: " Load the fixer and set up a series of commands, reset fixer variables, " clear caches, etc. " " Vader's 'Save' command will be called here for fixer variables. call ale#assert#SetUpFixerTest('filetype', 'fixer_name') After: " Reset fixers, variables, etc. " " Vader's 'Restore' command will be called here. call ale#assert#TearDownFixerTest() Execute(The default command should be correct): " AssertFixer checks the result of the loaded fixer function. AssertFixer {'command': ale#Escape('some-command') . ' --foo'} Execute(Check chained commands): " Same as above for linter tests. GivenCommandOutput ['v2.1.2'] " Given a List of commands, check all of them. " Given anything else, only the last result will be checked. AssertFixer [ \ ale#Escape('some-command') . ' --version', \ {'command': ale#Escape('some-command') . ' --foo'} \] < The full list of commands that will be temporarily defined for fixer tests given the above setup are as follows. `GivenCommandOutput [...]` - Define output for ale#command#Run. `AssertFixerCwd cwd` - Check the `cwd` for the fixer. `AssertFixer results` - Check the fixer results `AssertFixerNotExecuted` - Check that fixers will not be executed. =============================================================================== 4.3 Running Tests in a Windows VM *ale-development-windows-tests* Tests are run for ALE in a build of Vim 8 for Windows via AppVeyor. These tests can frequently break due to minor differences in paths and how escaping is done for commands on Windows. If you are a Linux or Mac user, running these tests locally can be difficult. Here is a process that will make that easier. First, you want to install a Windows image with VirtualBox. Install VirtualBox and grab a VirtualBox image for Windows such as from here: https://developer.microsoft.com/en-us/microsoft-edge/tools/vms/ NOTE: If you need to enter a password for the virtual machine at any point, the password is "Passw0rd!" without the double quotes. NOTE: If your trial period for Windows runs out, run the commands like the wallpaper tells you to. Your virtual machine will need to have PowerShell installed. Before you go any further, confirm that PowerShell is installed in your Windows virtual machine. Consult the VirtualBox documentation on how to install "Guest Additions." You probably want to install "Guest Additions" for most things to work properly. After you've loaded your virtual machine image, go into "Settings" for your virtual machine, and "Shared Folders." Add a shared folder with the name "ale", and set the "Folder Path" to the path to your ALE repository, for example: "/home/w0rp/ale" Find out which drive letter "ale" has been mounted as in Windows. We'll use "E:" as the drive letter, for example. Open the command prompt as an administrator by typing in `cmd` in the start menu, right clicking on the command prompt application, and clicking "Run as administrator." Click "Yes" when prompted to ask if you're sure you want to run the command prompt. You should type in the following command to mount the "ale" directory for testing, where "E:" is replaced with your drive letter. > mklink /D C:\testplugin E: < Close the administrator Command Prompt, and try running the command `type C:\testplugin\LICENSE` in a new Command Prompt which you are NOT running as administrator. You should see the license for ALE in your terminal. After you have confirmed that you have mounted ALE on your machine, search in the Start Menu for "power shell," run PowerShell as an administrator, and issue the following commands to install the correct Vim and Vader versions for running tests. > Add-Type -A System.IO.Compression.FileSystem Invoke-WebRequest ftp://ftp.vim.org/pub/vim/pc/vim80-586w32.zip -OutFile C:\vim.zip [IO.Compression.ZipFile]::ExtractToDirectory('C:\vim.zip', 'C:\vim') rm C:\vim.zip Invoke-WebRequest ftp://ftp.vim.org/pub/vim/pc/vim80-586rt.zip -OutFile C:\rt.zip [IO.Compression.ZipFile]::ExtractToDirectory('C:\rt.zip', 'C:\vim') rm C:\rt.zip Invoke-WebRequest https://github.com/junegunn/vader.vim/archive/c6243dd81c98350df4dec608fa972df98fa2a3af.zip -OutFile C:\vader.zip [IO.Compression.ZipFile]::ExtractToDirectory('C:\vader.zip', 'C:\') mv C:\vader.vim-c6243dd81c98350df4dec608fa972df98fa2a3af C:\vader rm C:\vader.zip < After you have finished installing everything, you can run all of the tests in Windows by opening a Command Prompt NOT as an administrator by navigating to the directory where you've mounted the ALE code, which must be named `C:\testplugin`, and by running the `run-tests.bat` batch file. > cd C:\testplugin run-tests < It will probably take several minutes for all of the tests to run. Be patient. You can run a specific test by passing the filename as an argument to the batch file, for example: `run-tests test/test_c_flag_parsing.vader` . This will give you results much more quickly. =============================================================================== 5. Contributing *ale-development-contributing* All integration of new code into ALE is done through GitHub pull requests. Using that tool streamlines the process and minimizes the time and effort required to e.g. ensure test suites are run for every change. As for any project hosted by GitHub, the choice of platform demands every contributor to take care to setup an account and configure it accordingly. Due to details of our process, a difference to many other GitHub hosted projects is that contributors who wish to keep the author fields for their commits unaltered need to configure a public email address in their account and profile settings. See: https://docs.github.com/en/account-and-profile/ Unless configuring GitHub to expose contact details, commits will be rewritten to appear by `USERNAME ` . =============================================================================== 5.1 Preparing a Release *ale-development-release* ALE offers release packages through GitHub, for two reasons: 1. Some users like to target specific release versions rather than simply installing the plugin from `master`. This includes users who create Linux distribution specific packages from GitHub releases. 2. The releases provide a nice way to get an overview of what has changed in ALE over time. ALE has no fixed release schedule. Release versions are created whenever the ALE developers feel the need to create one. ALE release versions follow the typical Semantic Versioning scheme. See: https://semver.org/ Minor version releases for ALE should be the most common, followed by patch releases. Every minor version release should be followed by a `vA.B.x` branch such as `v2.0.x` for version `2.0.0` and every following patch version before `2.1.0`. The `git` branch strategy for patches is to first merge a bug fix to `master`, and then `git cherry-pick` a patch to a branch for a specific version. ALE developers do not generally support anything but `master` or the last minor version. Generally ALE releases hit a major version only when there are breaking changes to a public ALE setting or function. A "public" setting or function is defined as any setting or function documented in the `:help` |ale.txt| file. Major ALE versions ought to be so rare that they only come once a year at most. ALE should not typically introduce any breaking changes. If there are ever to be any breaking changes made for ALE, there should first come a minor version release for ALE documenting all of the coming breaking changes to ALE. It should be described how users can prepare for a breaking change that is coming before it is done. To create a release for ALE, you will need sufficient permissions in GitHub. Once you do, follow these steps. 1. Create a new release draft, or edit an existing one. It helps to craft drafts ahead of time and write the last commit ID checked for release notes on the last update to a draft. See the releases page: https://github.com/dense-analysis/ale/releases 2. Examine `git log` and read changes made between the last ID checked, or the git tag of the previous release, and the current commit in `master`. 3. Write updates in separate sections (except where empty) for: 3.a. Breaking Changes 3.b. Deprecated Features 3.c. New Features 3.d. New Linters 3.e. New Fixers 3.f. Linter Enhancements 3.g. Fixer Enhancements 3.h. Bugs Fixed 4. Once you've finished writing the draft for the release, bump `s:current_ale_version` in `autoload/ale.vim` to the current version, and add a line to `test/test_ale_has.vader` to test for the version. See |ale#Has()| documentation for more information. 5. Commit the changes after `./run-tests --fast -q` passes. 6. Tag the release with `git tag vA.B.C`, replacing `A`, `B`, and `C` with the version numbers. See `git tag --list` for examples. 7. Run `git push` and `git push --tags` to push the commit and the tag. 8. Edit the release draft in GitHub, select the tag you just pushed, and publish the draft. 9. If you're creating a new major or minor version: `git checkout -b vA.B.x`, replacing `A` and `B` with the major and minor versions. `git push` the new branch, and the GitHub branch protection settings should automatically apply to the new release branch. 10. You have already completed the last step. Have fun creating ALE releases. Drink responsibly, or not at all, which is the preference of w0rp. =============================================================================== vim:tw=78:ts=2:sts=2:sw=2:ft=help:norl: