# Contributing

## Bugs

Please look at [Github Issues](https://github.com/awesomeWM/awesome/issues).

## Style

If you intend to patch and contribute to awesome, please respect the
following guidelines.

Imitate the existing code style. For concrete rules:

 - Use 4 spaces indentation, do not use tabulator characters;

 - Place braces alone on new lines, and do not place braces for single
   line statement where it is not needed, i.e.:

        if(foo)
            x = 1;

        if(foo)
        {
            x = 1;
            bar();
        }

 - Do not put a space after if, for, while or function call statements;

 - The preferred maximum line length is 80 characters;

 - Use `/* */` for comments;

 - Use the API: there is a list of `a_*()` functions you should use instead
   of the standard libc ones. There is also a common API for linked lists,
   tabulars, etc.;

 - Be *clear* in what you do;

 - Prefix your function names with the module they are enhancing,
   i.e. if you add a function to manipulate a tag, prefix it with `tag_`;

 - Write documentation for any new functions, options, whatever.

A vim modeline is set in each file to respect this.

### Documentation of Lua files

For documentation purposes LDoc---see
[here](https://stevedonovan.github.io/ldoc/manual/doc.md.html) for its
documentation---is used. Comments that shall be parsed by LDoc have the
following format:

    --- summary.
    -- Description; this can extend over
    -- several lines

    -----------------
    -- This will also do.

    --[[--
     Summary. A description
     ...;
    ]]

You can use the full power of
[Markdown](http://daringfireball.net/projects/markdown) with the extensions of
[Discount](http://www.pell.portland.or.us/~orc/Code/discount/) for markup in
the comments.

Every module and class should have a short description at its beginning which
should include `@author author`, `@copyright year author`,
`@release @AWESOME_VERSION@` and `@module module-name` or `@classmod class-name`.

Parameters of functions should be documented using
`@tparam <type> <parmname> <description>`, and return values via
`@treturn <type> <description>`.

For a more comprehensive description of the available tags see the [LDoc
documentation](https://stevedonovan.github.io/ldoc/manual/doc.md.html).

In addition to the regular tags provided by LDoc there are also some aliases
for typed parameters defined in `docs/config.ld`, e.g. `@client` for
`@tparam client.object`, `@tag` for `@tparam tag` and `@tab` for
`@tparam table`).

## Patches

If you plan to submit patches, you should follow the following guidelines.

### Commits

- make commits of logical units;
- do not modify piece of code not related to your commit;
- do not try to fix style of code you are not writing,
  it's just adding noise for no gain;
- check for unnecessary whitespace with `git diff --check` before committing;
- do not check in commented out code or unneeded files;
- provide a meaningful commit message;
- the first line of the commit message should be a short;
  description and should skip the full stop;
- if you want your work included, add a
  `Signed-off-by: Your Name <you@example.com>` line to the
  commit message (or just use the option `-s` when committing);
- make sure that you have tests for the bug you are fixing;
- if possible, add a unit test to the test suite under spec/.

### Patches

Submitting patches via pull requests on the Github project is the preferred
method.

#### Pull request
- create a [pull request](https://github.com/awesomeWM/awesome/pulls)

#### git-send-email
- use `git format-patch -M` to create the patch;
- do *not* PGP sign your patch;
- be *careful* doing cut & paste into your mailer, not to corrupt whitespaces;
- if you change, add or remove the user API, the associated documentation
  should be updated as well;
- send the patch to the list (`awesome-devel@naquadah.org`) if (and only if)
  the patch is ready for inclusion. If you use git-send-email(1), please *test*
  it first by sending email to yourself.