]> git.madduck.net Git - etc/vim.git/blob - CONTRIBUTING.md

madduck's git repository

Every one of the projects in this repository is available at the canonical URL git://git.madduck.net/madduck/pub/<projectpath> — see each project's metadata for the exact URL.

All patches and comments are welcome. Please squash your changes to logical commits before using git-format-patch and git-send-email to patches@git.madduck.net. If you'd read over the Git project's submission guidelines and adhered to them, I'd be especially grateful.

SSH access, as well as push access can be individually arranged.

If you use my repositories frequently, consider adding the following snippet to ~/.gitconfig and using the third clone URL listed for each project:

[url "git://git.madduck.net/madduck/"]
  insteadOf = madduck:

Merge pull request #60 from cirosantilli/contributing-guidelines
[etc/vim.git] / CONTRIBUTING.md
1 These contributing guidelines were accepted rather late in the history of this plugin, after much code had already been written.
2
3 If you find any existing behavior which does not conform to these guidelines, please correct it and send a pull request.
4
5 # General Rules
6
7 Every non local identifier must start with `g:vim_markdown_`.
8
9 # Documentation
10
11 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.
12
13 # Markdown Flavors
14
15 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:
16
17 - Features from the [original markdown](http://daringfireball.net/projects/markdown/syntax) are turned on by default. They may not even have an option that turns them off.
18
19 - Features from other markdown flavors *must* have an option that turns them on or off. If the feature is common enough across multiple versions of markdown, it may be turned on by default. This shall be decided by the community when the merge request is done.
20
21 - If possible, cite the exact point in the documentation of the flavor where a feature is specified. If the feature is not documented, you may also reference the source code itself of the implementation. This way, people who do not know that flavor can check if your implementation is correct.
22
23 - Do not use the name of a flavor for a feature that is used across multiple flavors. Instead, create a separate flavor option, that automatically sets each feature.
24
25     For example, fenced code blocks (putting code between pairs of three backticks) is not part of the original markdown, but is supported by [GFM](https://help.github.com/articles/github-flavored-markdown#fenced-code-blocks) and [Jekyll](http://jekyllrb.com/docs/configuration/).
26
27     Therefore, instead of creating an option `g:vim_markdown_gfm_fenced_code_block`, and an option `g:vim_markdown_jekyll_fenced_code_block`, create a single option `g:vim_markdown_fenced_code_block`.
28
29     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.
30
31 # Tests
32
33 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:
34
35 ```
36 ## Links
37
38 [Link text](link URL)
39
40 ... more correct link tests ...
41
42 ###### FAIL: should not be highlighted as a link
43
44 Text (with parenthesis) alone should not be highlighted as a link. (Issue #57)
45
46 ... more failed link tests ...
47
48 ## Code Blocks
49 ```