diff options
| -rw-r--r-- | CONTRIBUTING.md | 78 |
1 files changed, 78 insertions, 0 deletions
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ec9239c1..8cd1007a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -5,6 +5,11 @@ 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-new-options) +5. [In Case of Busses](#in-case-of-busses) <a name="guidelines"></a> @@ -12,6 +17,9 @@ 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. + 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 @@ -90,3 +98,73 @@ 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 guidlines 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 adduction, 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. |