116 lines
3.5 KiB
Markdown
116 lines
3.5 KiB
Markdown
# 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 <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)
|
|
|