Update the contributing guide to offer some more advice

This commit is contained in:
w0rp 2017-02-05 15:55:50 +00:00
parent 9a5fc6f932
commit eb410b4ee6

View File

@ -1,8 +1,10 @@
# Contributing to ALE # Contributing to ALE
1. [Guidelines](#guidelines) 1. [Guidelines](#guidelines)
2. [Creating Pull Requests](#pull-requests) 2. [Creating Issues](#issues)
3. [Creating Pull Requests](#compiling) 3. [Creating Pull Requests](#pull-requests)
1. [Adding a New Linter](#adding-a-new-linter)
2. [Adding New Options](#adding-new-options)
<a name="guidelines"></a> <a name="guidelines"></a>
@ -10,21 +12,44 @@
Have fun, and work on whatever floats your boat. Take It Easy :tm:. Have fun, and work on whatever floats your boat. Take It Easy :tm:.
When writing code, follow the [Google Vimscript Style Guide](https://google.github.io/styleguide/vimscriptguide.xml), and When writing code, follow the [Google Vimscript Style
run `vint -s` on your files to check for most of what the guide mentions and more. If you install this plugin and install Guide](https://google.github.io/styleguide/vimscriptguide.xml), and run `vint
[Vint](https://github.com/Kuniwak/vint), it will check your code while you type. -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
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
issue has already been reported, but you have some new insight, please add
a comment to the existing issue.
Please read the FAQ in the README before creating any issues. A feature
you desire may already exist and be documented, or the FAQ might explain
how to solve a problem you have already.
Please try and describe any issues reported with as much detail as you can
provide about your Vim version, the linter you were trying to run, your
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> <a name="pull-requests"></a>
# 2. Creating Pull Requests # 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 For code you write, make sure to credit yourself at the top of files you add,
some comments at the top of your VIM files. and probably those you modify. You can write some comments at the top of your
VIM files.
```vim ```vim
" Author: John Smith <john.smith@gmail.com> " Author: John Smith <john.smith@gmail.com>
" Description: This file adds support for awesomelinter to the best language ever. " Description: This file adds support for awesomelinter for the best language ever.
``` ```
If you want to credit multiple authors, you can comma separate them. If you want to credit multiple authors, you can comma separate them.
@ -33,34 +58,35 @@ If you want to credit multiple authors, you can comma separate them.
" Author: John Smith <john.smith@gmail.com>, Jane Doe <https://jane-doe.info> " Author: John Smith <john.smith@gmail.com>, Jane Doe <https://jane-doe.info>
``` ```
# 2.1. Adding a New Linter <a name="adding-a-new-linter"></a>
If you add a new linter, look for existing handlers first in the [handlers.vim](autoload/ale/handlers.vim) file. One of the handlers # 3.i. Adding a New Linter
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.vim](autoload/ale/handlers.vim) file, 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 If you add a new linter, look for existing handlers first in the
[README.md](README.md) file and in the Vim [help file](doc/ale.txt). The programs and linters are sorted alphabetically in the [handlers.vim](autoload/ale/handlers.vim) file. One of the handlers there may
table and list. 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.vim](autoload/ale/handlers.vim) file, and use the generic handler in
both places.
# 2.2. Adding New Options 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.
If you add new options to the plugin, make sure to document those new options in the [README.md](README.md) file, and also <a name="adding-new-options"></a>
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, and options specific to a particular linter should go in the section
for that linter.
<a name="compiling"></a> # 3.ii. Adding New Options
# 3. Compiling the Windows stdin wrapper 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.
To compile the stdin wrapper program for Windows, when updating the D program, you will need to compile the program with Linter options for customizing general argument lists should be named
[LDC](https://github.com/ldc-developers/ldc) in release mode. Download and install the Community edition of Visual Studio `g:ale_<filetype>_<linter>_options`, so that all linters can have similar
from [the Visual Studio website](https://www.visualstudio.com/downloads/) first before installing LDC. LDC typically comes in global variable names.
a ZIP you can just extract somewhere.
Make sure to compile with the 32-bit architecture flag, otherwise the EXE will not run on 32-bit machines. 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...`.
```
ldc2 -m32 -Oz -release stdin_wrapper.d -of=stdin-wrapper.exe
```