Add contributing guidelines and widget type templates
This commit is contained in:
Nguyễn Gia Phong
parent
5e7a5325f5
commit
ac86ebdb38
|
|
@ -6,6 +6,12 @@ read_globals = {
|
|||
"timer", -- deprecated, but used in older versions.
|
||||
}
|
||||
|
||||
include_files = {
|
||||
"*.lua", -- libraries
|
||||
"widgets/*.lua", -- officially supported widget types
|
||||
"templates/*.lua", -- officially supported widget types
|
||||
}
|
||||
|
||||
-- Warnings to be ignored
|
||||
ignore = {
|
||||
"212", -- Unused argument.
|
||||
|
|
|
|||
|
|
@ -0,0 +1,316 @@
|
|||
# How to contribute to Vicious
|
||||
|
||||
## Filing an Issue
|
||||
|
||||
* Ensure the bug was not already reported by searching GitHub Issues.
|
||||
* If you're unable to find an open issue addressing the problem,
|
||||
open a new one. Be sure to include a title and clear description,
|
||||
as much relevant information as possible, such as Awesome errors,
|
||||
and a config sample or an executable test case
|
||||
(using Vicious as a stand-alone library)
|
||||
demonstrating the expected behavior that is not occurring.
|
||||
|
||||
Please re-read your issue once again to avoid a couple of common mistakes
|
||||
(you can and should use this as a checklist):
|
||||
|
||||
* Is the description of the issue itself sufficient?
|
||||
Make sure that it's obvious
|
||||
- What the problem is
|
||||
- How it could be fixed
|
||||
- How your proposed solution would look like
|
||||
* Have you provide the versions of Vicious and related software?
|
||||
We would like to how you installed Vicious, which OS you're using,
|
||||
the version of the software or what kind of hardware you are trying
|
||||
to get information from.
|
||||
* Is the issue already documented?
|
||||
* Does the issue involve one problem, and one problem only?
|
||||
Some people seem to think there is a limit of issues they can or should open.
|
||||
There is no limit of issues they can or should open.
|
||||
While it may seem appealing to be able to dump all your issues
|
||||
into one ticket, that means that someone who solves one of your issues
|
||||
cannot mark the issue as closed.
|
||||
* Is anyone going to need the feature? Only post features that you
|
||||
(or an incapacitated friend you can personally talk to) require.
|
||||
Do not post features because they seem like a good idea.
|
||||
If they're really useful, they'll be requested by someone who requires them.
|
||||
|
||||
## Requesting for Merging a Patch
|
||||
|
||||
1. [Fork this repository](https://github.com/vicious-widgets/vicious/fork)
|
||||
2. Check out the source code with:
|
||||
|
||||
git clone git@github.com:YOUR_GITHUB_USERNAME/vicious.git
|
||||
cd vicious
|
||||
|
||||
3. Start working on your patch. If you want to add a new widget type,
|
||||
see the `templates` directory for a more detailed guide.
|
||||
4. Have a look at `helpers.lua` and `spawn.lua` for possible helper functions.
|
||||
5. Make sure your code follows the coding conventions below and check the code
|
||||
with `luacheck`. This *should fail* at first, but you can continually
|
||||
re-run it until you're done.
|
||||
|
||||
luacheck --config .luacheckrc .
|
||||
|
||||
6. Make sure your code works under all Lua versions claimed supported
|
||||
by Vicious, namely 5.1, 5.2 and 5.3.
|
||||
7. Update the copyright notices of the files you modified. Vicious is
|
||||
collectively licensed under GPLv2+, and to protect the freedom of the users,
|
||||
copyright holders need to be properly documented.
|
||||
8. Try to note your changes under `Changes.md`. If you find it is
|
||||
difficult to phrase the changes, you can leave it for us.
|
||||
9. [Add](https://git-scm.com/docs/git-add) the changes,
|
||||
[commit](https://git-scm.com/docs/git-commit) them
|
||||
and [push](https://git-scm.com/docs/git-push) the result, like this:
|
||||
|
||||
git add widgets/bar_baz.lua README.md
|
||||
git commit -m '[bar_baz] Add widget type'
|
||||
git add helpers.lua Changes.md
|
||||
git commit -m '[helpers] Fix foo'
|
||||
git push
|
||||
|
||||
10. Finally, [create a pull request](https://help.github.com/articles/creating-a-pull-request).
|
||||
We'll then review and merge it.
|
||||
|
||||
In any case, thank you very much for your contributions!
|
||||
|
||||
## Coding Conventions
|
||||
|
||||
This section introduces a guideline for writing idiomatic, robust
|
||||
and future-proof widget type code.
|
||||
|
||||
### Whitespces in Expressions and Statements
|
||||
|
||||
Avoid extraneous whitespace in the following situations:
|
||||
|
||||
* Immediately inside parentheses or brackets. Braces, however, are exceptions
|
||||
to this rule:
|
||||
|
||||
```lua
|
||||
foo(bar[1], { baz = 2 }) -- yes
|
||||
foo( bar[ 1 ], {baz = 2} ) -- no
|
||||
```
|
||||
|
||||
* Immediately before a comma, semicolon, or colon.
|
||||
* Immediately before the open parenthesis, braces, quote, etc.
|
||||
that starts the argument list of a function call; or the open braket
|
||||
that starts an indexing. In other words, prefer these:
|
||||
|
||||
```lua
|
||||
foo(bar, baz)
|
||||
foo{ bar, baz }
|
||||
foo"bar"
|
||||
foo[[bar]]
|
||||
foo[bar]
|
||||
```
|
||||
|
||||
* Trailing at the end of line or (newline) at the end of file.
|
||||
|
||||
Always surround these binary operators with a single space on either side:
|
||||
assignment (`=`), comparisons, Booleans (`and`, `or`, `not`).
|
||||
If operators with different priorities are used, consider adding whitespace
|
||||
around the operators with the lowest priorities. Use your own judgment;
|
||||
however, never use more than one space, and always have
|
||||
the same amount of whitespace on both sides of a binary operator.
|
||||
|
||||
### Indentation
|
||||
|
||||
Use 4 *spaces* per indentation level.
|
||||
|
||||
Continuation lines should align wrapped elements either vertically
|
||||
inside parentheses, brackets and braces, or using a hanging indent
|
||||
(the opening parenthesis of a parenthesized statement is the last
|
||||
non-whitespace character of the line, with subsequent lines being indented
|
||||
until the closing parenthesis), e.g.
|
||||
|
||||
```lua
|
||||
-- Vertically aligned
|
||||
long_function_call{ foo, bar,
|
||||
baz }
|
||||
|
||||
-- Hanging indentation
|
||||
long_function_call(
|
||||
foo, bar
|
||||
baz)
|
||||
```
|
||||
|
||||
The closing brace or braket on multiline constructs may either line up under
|
||||
the first character of the line that starts the construct, as in:
|
||||
|
||||
```lua
|
||||
long_function_call{
|
||||
foo = 1, bar = 2,
|
||||
baz = 3,
|
||||
}
|
||||
```
|
||||
|
||||
In this case, and this case only, the trailing comma is acceptable
|
||||
to avoid diff noises when more values are added,
|
||||
but since Vicious often deal with system APIs which rarely ever change,
|
||||
it's occasionally helpful to do so.
|
||||
|
||||
Trailing right parentheses, however, are not allowed.
|
||||
|
||||
### Maximum Line Length
|
||||
|
||||
Limit all *code* lines to a maximum of 80 characters.
|
||||
Comments and long strings need not to follow this restriction.
|
||||
|
||||
As one might have noticed, the syntatic sugars `f{<fields>}`
|
||||
(for `f({<fields>})`) and `f'<string>'` (or `f"<string>"`/`f[[<string>]]`,
|
||||
for `f('<string>')`) are espescially prefered to squeeze
|
||||
the line length to this limit.
|
||||
|
||||
### Blank Lines
|
||||
|
||||
Surround function definitions with a single blank line. Extra blank lines
|
||||
may be used (sparingly) to separate groups of related functions.
|
||||
Blank lines may be omitted between a bunch of related one-liners
|
||||
(e.g. a set of dummy implementations).
|
||||
Use blank lines in functions, sparingly, to indicate logical sections.
|
||||
|
||||
### Requiring Libraries
|
||||
|
||||
All standard libraries should be localized before used
|
||||
for the matter of performance.
|
||||
|
||||
`require`s should always be put at the top of the source file,
|
||||
just after the copyright header, and before module globals and constants,
|
||||
and grouped in the following order:
|
||||
|
||||
1. Standard libraries
|
||||
2. Related third-party libraries
|
||||
3. Local libraries
|
||||
|
||||
For example,
|
||||
|
||||
```lua
|
||||
local type = type
|
||||
local table = { concat = table.concat, insert = table.insert }
|
||||
|
||||
local awful = require"awful"
|
||||
|
||||
local helpers = require"vicious.helpers"
|
||||
```
|
||||
|
||||
### String Quotes
|
||||
|
||||
In Lua, single-quoted strings and double-quoted strings are the same,
|
||||
so the choice is totally up to you, but please be consistent within a module.
|
||||
When a string contains single or double quote characters, however,
|
||||
use the other one to avoid backslashes in the string. It improves readability:
|
||||
|
||||
```lua
|
||||
'"key": "value"' -- good
|
||||
"\"key\": \"value\"" -- no good
|
||||
```
|
||||
|
||||
It is preferable to add a newline immediately after the opening long bracket:
|
||||
|
||||
```lua
|
||||
foo = [[
|
||||
this is a really,
|
||||
really,
|
||||
really long text]]
|
||||
```
|
||||
|
||||
### Naming Conventions
|
||||
|
||||
Avoid using the characters `l` (lowercase letter el), `O` (uppercase letter oh),
|
||||
or `I` (uppercase letter eye) as single character variable names.
|
||||
In some fonts, these characters are indistinguishable from the 1's and 0's.
|
||||
|
||||
#### Constants
|
||||
|
||||
Constants are usually defined on a module level
|
||||
and written in all capital letters with underscores separating words.
|
||||
Examples include `MAX_OVERFLOW` and `TOTAL`.
|
||||
|
||||
|
||||
#### Function and Variable Names
|
||||
|
||||
Function names should be lowercase, with words separated by underscores
|
||||
as necessary to improve readability.
|
||||
|
||||
Variable names follow the same convention as function names.
|
||||
|
||||
When you find it difficult to give descriptive names,
|
||||
use the functions and variable anonymously.
|
||||
|
||||
### Performance Tips
|
||||
|
||||
Vicious is meant to be run as part of the Awesome window manager,
|
||||
thus any little overhead may defect the responsiveness of the UI.
|
||||
While Lua is famous for its performance, there are a few things
|
||||
one can do to make use of all of its power.
|
||||
|
||||
**Never** use global variables. This includes the standard libraries,
|
||||
which, again, must be localized before use. Remember, every widget type
|
||||
is to be called repeatedly every few seconds.
|
||||
|
||||
Use closures when possible:
|
||||
|
||||
* Define constants on the module level.
|
||||
* Avoid re-fetching the values that are not not meant to change.
|
||||
|
||||
However, declare a variable only when you need it, to avoid declaring it
|
||||
without an initial value (and therefore you seldom forget to initialize it).
|
||||
Moreover, you shorten the scope of the variable, which increases readability.
|
||||
|
||||
### Copyright Header
|
||||
|
||||
Vicious is released under the GNU GNU General Public License
|
||||
version 2 or later and each contributor holds the copyright
|
||||
on their contributions. To make this collective control effective,
|
||||
each source file must include a notice of the following format
|
||||
denoting the name of all authors
|
||||
|
||||
```lua
|
||||
-- <one line to give the program's name and a brief idea of what it does.>
|
||||
-- Copyright (C) <year> <name of author> <<email that can be use for contact>>
|
||||
--
|
||||
-- This file is part of Vicious.
|
||||
--
|
||||
-- Vicious is free software: you can redistribute it and/or modify
|
||||
-- it under the terms of the GNU General Public License as
|
||||
-- published by the Free Software Foundation, either version 2 of the
|
||||
-- License, or (at your option) any later version.
|
||||
--
|
||||
-- Vicious is distributed in the hope that it will be useful,
|
||||
-- but WITHOUT ANY WARRANTY; without even the implied warranty of
|
||||
-- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
||||
-- GNU General Public License for more details.
|
||||
--
|
||||
-- You should have received a copy of the GNU General Public License
|
||||
-- along with Vicious. If not, see <https://www.gnu.org/licenses/>.
|
||||
```
|
||||
|
||||
### Comments
|
||||
|
||||
Comments that contradict the code are worse than no comments.
|
||||
Always make a priority of keeping the comments up-to-date when the code changes!
|
||||
|
||||
You should use two spaces after a sentence-ending period
|
||||
in multi-sentence comments, except after the final sentence.
|
||||
|
||||
#### Block Comments
|
||||
|
||||
Block comments generally apply to some (or all) code that follows them,
|
||||
and are indented to the same level as that code. Each line of a block comment
|
||||
starts with `--` and a single space, unless text inside the comment is indented,
|
||||
or it is to comment out code.
|
||||
|
||||
Paragraphs inside a block comment are separated by a line containing `--` only.
|
||||
The best example is the copyright notice in the section above.
|
||||
|
||||
The `--[[...]]` style may only be used for commenting out source code.
|
||||
|
||||
#### Inline Comments
|
||||
|
||||
An inline comment is a comment on the same line as a statement.
|
||||
Inline comments should be separated by at least two spaces from the statement.
|
||||
They should start with `-- `.
|
||||
|
||||
## Influences
|
||||
|
||||
These contributing guideline are heavily influenced by that of `youtube-dl`,
|
||||
PEP 8, Programming in Lua and the performance tips in Lua Programming Gems.
|
||||
|
|
@ -0,0 +1,48 @@
|
|||
# Widget type templates
|
||||
|
||||
Before writing a new widget type, make sure to ask yourself if anyone is going
|
||||
to need the feature. Only widget types that you (or an incapacitated friend
|
||||
you can personally talk to) require would be merged. Do not file PRs because
|
||||
they seem like a good idea. If they're really useful, they'll be requested
|
||||
in the issue tracker.
|
||||
|
||||
Additionally, too simple widget types (e.g. an one-liner) and those that
|
||||
are not modular enough are very unlikely to be merged. By *modular*, we mean
|
||||
|
||||
> constructed with standardized units or dimensions
|
||||
> allowing flexibility and variety in use
|
||||
|
||||
If all the above conditions are met, you can start from one of the templates
|
||||
in this directory:
|
||||
|
||||
* `sync.lua`: synchronous widget type that does not fork
|
||||
* `async.lua`: asynchronous widget type for fetching informations using
|
||||
a command-line utility. As a rule of thumb, if your widget type uses
|
||||
`io.popen`, you would need to refactor it to use async facilities.
|
||||
|
||||
Your widget types should be placed in `widgets`: the `contrib` directory
|
||||
exists only for historical reasons and is barely maintained anymore.
|
||||
The filenames should be of the form `<name>_<platform>.lua`, whereas
|
||||
|
||||
* `<name>` is a single (alphanumeric) word, preferably in lowercase
|
||||
* `<platform>` is the OS that the widget type works on.
|
||||
At the time of writing these are supported:
|
||||
- `freebsd`: FreeBSD
|
||||
- `openbsd`: OpenBSD
|
||||
- `bsd`: all \*BSDs listed above
|
||||
- `linux`: GNU/Linux
|
||||
- `all`: all of the above
|
||||
|
||||
Please be aware of `luacheck`, which may help you during the progress.
|
||||
From `widgets`, run
|
||||
|
||||
luacheck --config .luacheckrc ..
|
||||
|
||||
After finishing the widget type, you should document its usage in the project's
|
||||
`README.md`. Try to provide at least
|
||||
|
||||
* A brief description
|
||||
* The list of supported platforms
|
||||
* Type and structures of the arguments that the widget type passes
|
||||
(`format` and `warg`), with unused parameters omitted
|
||||
* Type and structure of the return value
|
||||
|
|
@ -0,0 +1,28 @@
|
|||
-- template for asynchronous widet types
|
||||
-- Copyright (C) 2019 Nguyễn Gia Phong
|
||||
--
|
||||
-- This file is part of Vicious.
|
||||
--
|
||||
-- Vicious is free software: you can redistribute it and/or modify
|
||||
-- it under the terms of the GNU General Public License as
|
||||
-- published by the Free Software Foundation, either version 2 of the
|
||||
-- License, or (at your option) any later version.
|
||||
--
|
||||
-- Vicious is distributed in the hope that it will be useful,
|
||||
-- but WITHOUT ANY WARRANTY; without even the implied warranty of
|
||||
-- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
||||
-- GNU General Public License for more details.
|
||||
--
|
||||
-- You should have received a copy of the GNU General Public License
|
||||
-- along with Vicious. If not, see <https://www.gnu.org/licenses/>.
|
||||
|
||||
local helpers = require"vicious.helpers"
|
||||
|
||||
return helpers.setasyncall{
|
||||
async = function (format, warg, callback)
|
||||
-- In here there should be some asynchronous function
|
||||
-- from vicious.spawn or helpers.sysctl_async
|
||||
-- that call callback on the result.
|
||||
end }
|
||||
|
||||
-- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80
|
||||
|
|
@ -0,0 +1,25 @@
|
|||
-- template for synchronous widet types
|
||||
-- Copyright (C) 2019 Nguyễn Gia Phong
|
||||
--
|
||||
-- This file is part of Vicious.
|
||||
--
|
||||
-- Vicious is free software: you can redistribute it and/or modify
|
||||
-- it under the terms of the GNU General Public License as
|
||||
-- published by the Free Software Foundation, either version 2 of the
|
||||
-- License, or (at your option) any later version.
|
||||
--
|
||||
-- Vicious is distributed in the hope that it will be useful,
|
||||
-- but WITHOUT ANY WARRANTY; without even the implied warranty of
|
||||
-- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
||||
-- GNU General Public License for more details.
|
||||
--
|
||||
-- You should have received a copy of the GNU General Public License
|
||||
-- along with Vicious. If not, see <https://www.gnu.org/licenses/>.
|
||||
|
||||
local helpers = require"vicious.helpers"
|
||||
|
||||
return helpers.setcall(function (format, warg)
|
||||
-- Do the processing and return a table here.
|
||||
end)
|
||||
|
||||
-- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80
|
||||
Loading…
Reference in New Issue