documentation/CONTRIBUTING-CODE.md

   1 <!--
   2 This is part of the VimFx documentation.
   3 Copyright Simon Lydell 2015.
   4 See the file README.md for copying conditions.
   5 -->
   6
   7 # Contributing code
   8
   9 ## Localizations
  10
  11 Contribute your localization! Copy the `extension/locale/en-US` directory and go
  12 wild!
  13
  14
  15 ## Code
  16
  17 Create a new topic branch, based on either master or develop. **Note:** For now,
  18 _always_ base it on **develop**.
  19
  20     git checkout -b my-topic-branch master
  21     # or
  22     git checkout -b my-topic-branch develop
  23
  24 Code! Try to follow the following simple rules:
  25
  26 - Always use parenthesis when calling functions.
  27 - Always use explicit `return`s, unless the function is a one-liner.
  28 - Always use single quotes, unless you use interpolation.
  29 - Prefer interpolation over concatenation, both in strings and in regexes.
  30 - Always use the following forms (not any aliases):
  31   - `true` and `false`
  32   - `==` and `!=`
  33   - `and` and `or`
  34   - `not`
  35 - Put spaces inside `[]` and `{}` when destructuring and interpolating, but not
  36   in array and object literals.
  37 - Comment when necessary. Comments should be full sentences.
  38 - Try to keep lines at most 80 characters long.
  39 - Indent using two spaces.
  40
  41 See [tools.md] for how to **build,** **lint,** and **run the tests.**
  42
  43 Break up your pull request in several commits if necessary. The first line of
  44 commit messages should be a short summary. Add a blank line and then a nicely
  45 formatted markdown description after it if needed.
  46
  47 Finally send a pull request to same branch as you based your topic branch on
  48 (master or develop).
  49
  50 [tools.md]: tools.md
  51
  52
  53 ## Versioning and branches
  54
  55 Currently, no more updates are planned for 0.5.x = master branch. **Please only
  56 contribute to the develop branch for now.** It contains quite a bit of backwards
  57 incomptaible improvements, and will be released as 0.6.0 as soon as it is ready.
  58 That will be the last “big” release. Then we’ll switch to a more rapid release
  59 cycle, detailed below.
  60
  61 ### Vision
  62
  63 VimFx uses three numbers to describe its version: x.y.z, or major.minor.patch.
  64 However, in reality it is more like 0.y.z. The first number (major) won’t
  65 change until we feel that we don’t have any major changes coming. So until then
  66 it is only worth describing the two other numbers.
  67
  68 The middle number (minor) is incremented when a release contains new features,
  69 major refactors or changes to defaults. The idea is that when a user installs a
  70 new minor release, they should expect changes that they need to get familiar
  71 with.
  72
  73 The last number (patch) is incremented when a release contains only (simple)
  74 bugfixes, new localizations and updates to localizations. If a user installs a
  75 new patch release they shouldn’t have to get familiar with anything. Things
  76 should be like they were before, just a little better.
  77
  78 VimFx uses two branches: **master** and **develop**. master is the latest
  79 stable version plus trivial bugfixes. develop is the next minor version. master
  80 is merged into develop when needed, and develop is merged into master before it
  81 is going to be released.
  82
  83 In short, “backwards-incomptaible” changes and new features go into the develop
  84 branch, while most other things go into the master branch.