CONTRIBUTING.md

   1 # Contributing
   2
   3 ## Reporting issues
   4
   5 _Please_ read the following four lines!
   6
   7 - Use **English.**
   8 - Search for **duplicates**—also closed issues.
   9 - Bugs: Include **VimFx version**, Firefox version, OS and keyboard layout.
  10 - Feature requests: Include a specific detailed **use case** example.
  11
  12
  13 ---
  14
  15
  16 ## Localizing
  17
  18 Contribute your localization! See `locale` folder.
  19
  20 Send your pull request to the **master** branch (no matter if it is a new
  21 locale or an update to an existing one).
  22
  23
  24 ## Developing
  25
  26 ### Versioning and branches
  27
  28 VimFx uses three numbers to describe its version: x.y.z, or major.minor.patch.
  29 However, in reality it is more like 0.y.z. The first number (major) won’t
  30 change until we feel that we don’t have any major changes coming. So until then
  31 it is only worth describing the two other numbers.
  32
  33 The middle number (minor) is incremented when a release contains new features,
  34 major refactors or changes to defaults. The idea is that when a user installs a
  35 new minor release, they should expect changes that they need to get familiar
  36 with.
  37
  38 The last number (patch) is incremented when a release contains only (simple)
  39 bugfixes, new localizations and updates to localizations. If a user installs a
  40 new patch release they shouldn’t have to get familiar with anything. Things
  41 should be like they were before, just a little better.
  42
  43 VimFx uses two branches: **master** and **develop**. master is the latest
  44 stable version plus trivial bugfixes. develop is the next minor version. master
  45 is merged into develop when needed, and develop is merged into master before it
  46 is going to be released.
  47
  48 In short, “backwards-incomptaible” changes and new features go into the develop
  49 branch, while most other things go into the master branch.
  50
  51 ### Pull requests
  52
  53 Create a new topic branch, based on either master or develop. See above.
  54
  55     git checkout -b myTopicBranch master
  56     # or
  57     git checkout -b myTopicBranch develop
  58
  59 Code! Try to follow the following simple rules:
  60
  61 - Always use parenthesis when calling functions. (Except `require`.)
  62 - Always use explicit `return`s, unless the function is a one-liner.
  63 - Always use single quotes, unless you use interpolation.
  64 - Prefer interpolation over concatenation, both in strings and in regexes.
  65 - Always use the following forms (not any aliases):
  66   - `true` and `false`
  67   - `==` and `!=`
  68   - `and` and `or`
  69   - `not`
  70 - Put spaces inside `[]` and `{}` when destructuring and interpolating, but not
  71   in array and object literals.
  72 - Comment when necessary. Comments should be full sentences.
  73 - Try to keep lines at most 80 characters long.
  74 - Indent using two spaces.
  75
  76 Break up your pull request in several commits if necessary. The first line of
  77 commit messages should be a short summary. Add a blank line and then a nicely
  78 formatted markdown description after it if needed.
  79
  80 Finally send a pull request to same branch as you based your topic branch on
  81 (master or develop).
  82
  83 ### Tips:
  84
  85 - Compile the .coffee files with the **`--bare`** option! Otherwise you will
  86   get errors.
  87 - Run `coffee -cbw .` from the root of the project to automatically compile on
  88   changes.
  89 - Put a file called exactly `VimFx@akhodakivskiy.github.com` in the extensions/
  90   folder of a Firefox profile, containing the absolute path to the extension/
  91   folder in the project. Then you just need to restart Firefox (use some
  92   add-on!) after each change. More details in this [MDN article][mdn-extdevenv].
  93 - Only create tickets for issues and feature requests in English. Otherwise
  94   duplicate tickets in different languages will pile up.
  95
  96 [mdn-extdevenv]: https://developer.mozilla.org/en-US/docs/Setting_up_extension_development_environment#Firefox_extension_proxy_file