From 6f7dfa556f5365cc4d17350b052093bbc76a7852 Mon Sep 17 00:00:00 2001 From: Lukas Baumann Date: Mon, 9 Aug 2021 03:51:54 +0200 Subject: [PATCH] Delete CONTRIBUTING.rst --- CONTRIBUTING.rst | 344 ----------------------------------------------- 1 file changed, 344 deletions(-) delete mode 100644 CONTRIBUTING.rst diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst deleted file mode 100644 index cc9ff3e..0000000 --- a/CONTRIBUTING.rst +++ /dev/null @@ -1,344 +0,0 @@ -Contribution Guidelines -======================= - -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 ------------------------------- - -#. `Fork this repository`_ -#. Check out the source code with:: - - git clone https://github.com/YOUR_GITHUB_USERNAME/vicious.git - cd vicious - -#. Start working on your patch. If you want to add a new widget type, - see the ``templates`` directory for a more detailed guide. -#. Have a look at ``helpers.lua`` and ``spawn.lua`` - for possible helper functions. -#. 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 tools/luacheckrc . - -#. Make sure your code works under all Lua versions claimed supported - by Vicious, namely 5.1, 5.2 and 5.3. -#. 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. -#. Try to note your changes under ``CHANGELOG.rst``. If you find it is - difficult to phrase the changes, you can leave it for us. -#. Add_ the changes, commit_ them and 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 CHANGELOG.rst - git commit -m '[helpers] Fix foo' - git push - -#. Finally, `create 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. - -Whitespace in Expressions and Statements -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Avoid extraneous whitespace in the following situations: - -* Immediately inside parentheses or brackets. Braces, however, are exceptions - to this rule: - - .. code-block:: 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 bracket - that starts an indexing. In other words, prefer these: - - .. code-block:: 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. - -.. code-block:: lua - - -- Vertically aligned - long_function_call{ foo, bar, - baz } - - -- Hanging indentation - long_function_call( - foo, bar - baz) - -The closing brace or bracket on multi-line constructs may either line up under -the first character of the line that starts the construct, as in: - -.. code-block:: 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 -^^^^^^^^^^^^^^^^^^^ - -If possible, try to limit all *code* lines to a maximum -of 80 characters. In case you find some lines in your patch would be -more readable exceeding this limit, feel free to discuss with us. -Comments and long strings need not to follow this restriction however. - -As one might have noticed, the syntactic sugars ``f{}`` -(for ``f({})``) and ``f''`` -(or ``f""``/``f[[]]``, for ``f('')``) -are especially preferred 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, - -.. code-block:: 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: - -.. code-block:: lua - - '"key": "value"' -- good - "\"key\": \"value\"" -- no good - -It is preferable to add a newline immediately after the opening long bracket: - -.. code-block:: 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 - -.. code-block:: 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 ``--`` and one single space. - -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. - -.. _Fork this repository: https://github.com/vicious-widgets/vicious/fork -.. _Add: https://git-scm.com/docs/git-add -.. _commit: https://git-scm.com/docs/git-commit -.. _push: https://git-scm.com/docs/git-push -.. _create a pull request: - https://help.github.com/articles/creating-a-pull-request