Merge pull request #241 from alexconst/fix/hash_comments

[etc/vim.git] / CONTRIBUTING.md

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 7b5122afdac0cbd25ea296fc8ef229d9435a3806..832072dc4c40d2efa99c6d182b404732cbd17d93 100644 (file)
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -8,7 +8,9 @@ Every non local identifier must start with `g:vim_markdown_`.
 
 # 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
 
@@ -36,12 +38,19 @@ If you wish to have a behavior that differs from that style guide, add an option
 
 # Tests
 
-All new features must have tests. We don't require unit tests: tests that require users to open markdown code in Vim and check things manually are accepted, but you should point clearly to where the tests are.
+All new features must have unit tests.
+
+# Issues
 
-Wherever possible, use test cases from the [karlcow'w Markdown Test Suite](https://github.com/karlcow/markdown-testsuite), and link to the relevant test files on your merge request.
+Issues are tracked within GitHub.
 
-If a test does not exist there yet, make a pull request to them, and link to that pull request on the pull request you make here.
+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):
 
-If the test you want to do is not appropriate for the Markdown Test Suite, create it only under the `test/` directory here.
+```
+Minimal example:
 
-If we start disagreeing too often on what is appropriate or not, we will fork off that repository.
+    ```
+    =
+    ```
+    bad!
+```