Merge pull request #297 from KainokiKaede/master

[etc/vim.git] / CONTRIBUTING.md

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index d6716ce3b04ef876e4350f29d137403344f81eb5..86912a4a67ac6b7f9f33041e17539c0eaca3f2ed 100644 (file)
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,16 +1,20 @@
+# CONTRIBUTING
+
 These contributing guidelines were accepted rather late in the history of this plugin, after much code had already been written.
 
 If you find any existing behavior which does not conform to these guidelines, please correct it and send a pull request.
 
-# General Rules
+## General Rules
 
 Every non local identifier must start with `g:vim_markdown_`.
 
-# Documentation
+## Documentation
+
+Every new feature must be documented under in the [README.md](README.md). Documentation must be written in [GFM](https://help.github.com/articles/github-flavored-markdown) since GitHub itself is the primary to HTML converter used. In particular, remember that GFM adds line breaks at single newlines, so just forget about the 70 characters wide rule.
 
-Every new feature must be documented under in the [README.md](README.md). Documentation must be written in [GFM](https://help.github.com/articles/github-flavored-markdown) since Github itself is the primary to HTML converter used. In particular, remember that GFM adds line breaks at single newlines, so just forget about the 70 characters wide rule.
+Vim help file [doc/vim-markdown.txt](doc/vim-markdown.txt) will be generated from [README.md](README.md) by `make doc` using [vim-tools](https://github.com/xolox/vim-tools).
 
-# Markdown Flavors
+## Markdown Flavors
 
 There are many flavors of markdown, each one with an unique feature set. This plugin uses the following strategy to deal with all those flavors:
 
@@ -28,22 +32,27 @@ There are many flavors of markdown, each one with an unique feature set. This pl
 
     Next, if there are many more than one Jekyll feature options, create a `g:vim_markdown_jekyll` option that turns them all on at once.
 
-# Tests
+## Style
 
-All new features must have tests. While we don't require unit tests, which are too hard to do in certain cases, you should create a test under the `test/` directory with a predictable name which allows other users to quickly test your feature. Good tests should explain their expected input / output behavior. Failing test should be marked with `FAIL` somewhere near the test, possibly explaining why it fails. For example:
+When choosing between multiple valid Markdown syntaxes, the default behavior must be that specified at: <http://www.cirosantilli.com/markdown-styleguide>
 
-```
-## Links
+If you wish to have a behavior that differs from that style guide, add an option to turn it on or off, and leave it off by default.
 
-[Link text](link URL)
+## Tests
 
-... more correct link tests ...
+All new features must have unit tests.
 
-###### FAIL: should not be highlighted as a link
+## Issues
 
-Text (with parenthesis) alone should not be highlighted as a link. (Issue #57)
+Issues are tracked within GitHub.
 
-... more failed link tests ...
+When reporting issues, your report is more effective if you include a minimal example file that reproduces the problem. Try to trim out as much as possible, until you have the smallest possible file that still reproduces the issue. Paste the example inline into your issue report, quoted using four spaces at the beginning of each line, like this example from issue [#189](https://github.com/plasticboy/vim-markdown/issues/189):
+
+```
+Minimal example:
 
-## Code Blocks
+    ```
+    =
+    ```
+    bad!
 ```