diff --git a/.luacheckrc b/.luacheckrc index 6c05d07..d98f02c 100644 --- a/.luacheckrc +++ b/.luacheckrc @@ -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. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..ba297be --- /dev/null +++ b/CONTRIBUTING.md @@ -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{}` +(for `f({})`) and `f''` (or `f""`/`f[[]]`, +for `f('')`) 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 +-- +-- Copyright (C) <> +-- +-- 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 . +``` + +### 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. diff --git a/templates/README.md b/templates/README.md new file mode 100644 index 0000000..80a9ea9 --- /dev/null +++ b/templates/README.md @@ -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 `_.lua`, whereas + +* `` is a single (alphanumeric) word, preferably in lowercase +* `` 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 diff --git a/templates/async.lua b/templates/async.lua new file mode 100644 index 0000000..ebc2308 --- /dev/null +++ b/templates/async.lua @@ -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 . + +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 diff --git a/templates/sync.lua b/templates/sync.lua new file mode 100644 index 0000000..6b2b15f --- /dev/null +++ b/templates/sync.lua @@ -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 . + +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