documentation/CONTRIBUTING-CODE.md

   1 <!--
   2 This is part of the VimFx documentation.
   3 Copyright Simon Lydell 2015, 2016.
   4 See the file README.md for copying conditions.
   5 -->
   6
   7 # Contributing code
   8
   9 **This document is meant to _help,_ not to scare you off!** Contributions are
  10 more than welcome. Don’t be afraid to make mistakes–we’ll help you out!
  11
  12
  13 ## Localizations
  14
  15 Contribute your localization! Copy the `extension/locale/en-US` directory and go
  16 wild! Usually, it’s best to stick to the master branch.
  17
  18 Tip: If you’re translating into, for example, Swedish, run `gulp sync-locales
  19 --sv-SE?` to see how many percent is done. All lines (including line numbers)
  20 that don’t differ compared to “en-US” are also printed, letting you know what’s
  21 left to do. Substitute “sv-SE” with the locale you’re working on.
  22
  23 Also, don’t worry if you can’t get a 100% difference compared to “en-US.”
  24 Sometimes text strings are very short and will look identical in both languages.
  25 That’s completely OK.
  26
  27
  28 ## Code
  29
  30 Create a new topic branch, based on either master or develop.
  31
  32     git checkout -b my-topic-branch master
  33     # or
  34     git checkout -b my-topic-branch develop
  35
  36 Code! Try to follow these simple rules:
  37
  38 - Always use parentheses when calling functions.
  39 - Always use braces for object literals.
  40 - Always use explicit `return`s, unless the function is a one-liner.
  41 - Always use single quotes, unless you use interpolation.
  42 - Prefer interpolation over concatenation, both for strings and regexes.
  43 - Always use the following forms (not any aliases):
  44   - `true` and `false`
  45   - `==` and `!=`
  46   - `and` and `or`
  47   - `not`
  48 - Never use `++` and `--`.
  49 - Never put spaces directly inside `[]` and `{}`.
  50 - Never put spaces before or more than one space after `:` in object literals.
  51 - Never use `when ... then` in `switch`es; replace `then` with a newline.
  52 - Avoid vertical alignment of code (such as aligning `=`s).
  53 - Comment when necessary. Comments should be full sentences.
  54 - Keep lines at most 80 characters long.
  55 - Indent using two spaces.
  56 - Commit no `console.log(...)`s (but do use them when debugging).
  57
  58 See [tools.md] for how to **build,** **lint,** and **run the tests.**
  59
  60 Break up your pull request in several commits if necessary. The first line of
  61 commit messages should be a short summary. If needed, add a blank line and then
  62 a nicely formatted markdown description.
  63
  64 Finally send a pull request to same branch as you based your topic branch on
  65 (master or develop).
  66
  67 [tools.md]: tools.md
  68
  69
  70 ## Versioning and branches
  71
  72 VimFx uses three numbers to describe its version: x.y.z, or major.minor.patch.
  73
  74 Version 1.0.0 will soon be released. When that’s the case, the first number
  75 (major) will only be incremented when there are backwards-incompatible changes,
  76 such as changes to defaults or to the [config file API]. This should be avoided.
  77 The idea is that when a user installs a new major release, they should expect
  78 changes that they need to get familiar with.
  79
  80 The middle number (minor) is incremented when a release contains new features,
  81 or larger changes/refactors to code. Users should expect things to be roughly
  82 the same, but with a few new features (and the potential bugs along with them),
  83 when installing a new minor release.
  84
  85 The last number (patch) is incremented when a release contains only (simple)
  86 bugfixes, new localizations and updates to localizations. If a user installs a
  87 new patch release they shouldn’t have to get familiar with anything. Things
  88 should be like they were before, just a little better. Code released as a patch
  89 version should ideally have a low risk of bugs.
  90
  91 VimFx uses two branches: **master** and **develop**. master is the latest
  92 stable version plus trivial bugfixes. develop is the next minor version. master
  93 is merged into develop when needed, and develop is merged into master before it
  94 is going to be released.
  95
  96 In short, “backwards-incompatible” changes and new features go into the develop
  97 branch, while most other things go into the master branch.
  98
  99 Trying to choose the right branch is important in order to be able to keep a
 100 rapid release cycle.
 101
 102 [config file API]: api.md