# 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 and @module module-name or @classmod class-name.

Parameters of functions should be documented using @tparam , and return values via @treturn .

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 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)

generated by LDoc 1.4.2