Skip to content

Latest commit

 

History

History
218 lines (164 loc) · 6.24 KB

CONTRIBUTING.md

File metadata and controls

218 lines (164 loc) · 6.24 KB
Raw

Contributing

Thank you for contributing to vimperator-labs!

Following are some guidelines designed to make the progress as smooth as possible. If you have any questions, feel free to drop by #vimperator@freenode or create an issue.

Issues

A few things to keep in mind when creating a new issue:

  • Follow the issue template
  • Attach relevant configuration or RC file if applicable (e.g. your .vimperatorrc or part of it).
  • Check if a fresh profile solves the issue
    • $ firefox -no-remote -P
  • Confirm if it works without your configuration
    • $ firefox -no-remote -P <fresh profile> -vimperator "+u NONE"

Pull requests

  • Title and commit message(s) should include relevant issue ID(s)
  • For any new or changed feature, AsciiDoc documentation and an entry in the NEWS file is required for the patch to be accepted.

Development installation

Creating and installing a new XPI file after each update is cumbersome. Instead, create an extension linking to the vimperator directory, for example of a Git clone.

  1. Find the location your Firefox profile
    • E.g. /home/user/.mozilla/firefox/<hash>.default
  2. Go into the extensions directory
  3. Delete [email protected]
  4. Create a [email protected] text file
    • Add the absolute path to your Vimperator directory
    • E.g. /home/user/code/vimperator-labs/vimperator
  5. Restart Firefox

Hacking

If you've taken to hacking Vimperator source code, we hope that you'll share your changes. In case you do, please keep the following in mind, and we'll be happy to accept your patches.

Documentation

First of all, all new features and all user-visible changes to existing features need to be documented. That means editing the appropriate help files and adding a NEWS entry where appropriate. When editing the NEWS file, you should add your change to the top of the list of changes. If your change alters an interface (key binding, command) and is likely to cause trouble, prefix it with IMPORTANT:, otherwise, place it below the other IMPORTANT entries. If you're not sure if your change merits a news entry, or if it's important, please ask.

Coding Style

In general: Just look at the existing source code!

We try to target experienced JavaScript developers who do not necessarily need to have a good understanding of Vimperator's source code, nor necessarily understand in-depth concepts of other languages like Lisp or Python. Therefore, the coding style should feel natural to any JavaScript developer. Of course, this does not mean, you have to avoid all new JavaScript features like list comprehension or generators. Use them, when they make sense, but don't use them when the resulting code is hard to read.

Please stick to using only standards compliant JavaScript.

The most important style issues are:

  • Use 4 spaces to indent things, no tabs, not 2, nor 8 spaces. If you use Vim, this should be taken care of automatically by the modeline (like the one below).

  • No trailing whitespace.

  • Use " for enclosing strings instead of ', unless using ' avoids escaping of lots of ":

    alert("foo")

alert('foo')

  • Use // regexp literals rather than RegExp constructors, unless you're constructing an expression on the fly, or RegExp constructors allow you to escape less /s than the additional escaping of special characters required by string quoting:

    // Good
/application\/xhtml\+xml/
RegExp("http://(www\\.)vimperator.org/(.*)/(.*)")

// Bad
RegExp("application/xhtml\\+xml")
/http:\/\/(www\.)vimperator.org\/(.*)\/(.*)/

  • Exactly one space after if/for/while/catch etc. and after a comma, but none after a parenthesis or after a function call:

    for (pre; condition; post)
alert("foo");

  • Bracing is formatted as follows:

    function myFunction () {
    if (foo)
        return bar;
    else {
        baz = false;
        return baz;
    }
}
var quux = frob("you",
    {
        a: 1,
        b: 42,
        c: {
            hoopy: "frood"
        }
    });

    When in doubt, look for similar code.

  • No braces for one-line conditional statements:

    if (foo)
    frob();
else
    unfrob();

  • Prefer the use of let over var i.e. only use var when required.

    For more details, see: https://developer.mozilla.org/en/New_in_JavaScript_1.7#Block_scope_with_let

  • Reuse common local variable names. E.g. elem is generally used for element, win for windows, func for functions, ret for return values etc.

  • Prefer // over /* */ comments (exceptions for big comments are usually OK):

    // Good
if (HACK) // TODO: remove hack

// Bad
if (HACK) /* TODO: remove hack */

  • Documentation comment blocks use /** ... */ Wrap these lines at 80 characters.

  • Only wrap lines if it makes the code obviously clearer. Lines longer than 132 characters should probably be broken up rather than wrapped anyway.

  • Use UNIX new lines (\n), not windows (\r\n) or old Mac ones (\r).

  • Prefer Array iterator functions Array#forEach and Array#map over loops and array comprehensions.

  • Avoid using new with constructors where possible, and use [] and {} rather than new Array or new Object:

    // Good
RegExp("^" + foo + "$")
Function(code)
new Date

// Bad
new RegExp("^" + foo + "$")
new Function(code)
Date() // Right if you want a string-representation of the date

  • Don't use abbreviations for public methods:

    // Good
function splitString()...
let commands = ...;
let cmds = ...; // Since it's only used locally, abbreviations are ok, but so are the full names

// Bad
function splitStr()

Testing/Optimization

TODO:

  • Add some information here about testing/validation/etc.
  • Information about how/when to use :regressions might be nice.
  • Additionally, maybe there should be some benchmark information here, something to let a developer know what's "too" slow...? Or general guidelines about optimization?