diff options
Diffstat (limited to 'CONTRIBUTING.org')
| -rw-r--r-- | CONTRIBUTING.org | 92 |
1 files changed, 92 insertions, 0 deletions
diff --git a/CONTRIBUTING.org b/CONTRIBUTING.org new file mode 100644 index 0000000..755ed87 --- /dev/null +++ b/CONTRIBUTING.org @@ -0,0 +1,92 @@ +#+title: Contributing guidelines +#+author: Andrey Orst +#+email: andreyorst@gmail.com +#+date: 2020-10-24 + +Please read the following document to make collaborating on the project easier for both sides. + +* Reporting bugs +If you've encountered a bug, do the following: + +- Check if the documentation has information about the problem you have. + Maybe this isn't a bug, but a desired behavior. +- Check past and current issues, maybe someone had reported your problem already. + If there's no issue, describing your problem, or there is, but it is closed, please create new issue, and link all closed issues that relate to this problem, if any. +- Tag issue with a =BUG:= at the beginning of the issue name. + + +* Suggesting features and/or changes +Before suggesting a feature, please check if this feature wasn't requested before. +You can do that in the issues, by filtering issues by =FEATURE:=. +If no feature found, please file new issue, and tag it with a =FEATURE:= at the beginning of the issue name. + + +* Contributing changes +Please do. + +When deciding to contribute a large amount of changes, first consider opening a =DISCUSSION:= type issue, so we could first decide if such dramatic changes are in the scope of the project. +This will save your time, in case such changes are our of the project's scope. + +If you're contributing a bugfix, please open an =BUG:= issue first, unless someone already did that. +All bug related merge requests must have a linked issues with a meaningful explanation and steps of reproducing a bug. +Small fixes are also welcome, and doesn't require filing an issue, although we may ask you to do so. + +** Writing code +When writing code, consider following the existing style without applying dramatic changes to formatting unless really necessary. +For this particular project, please follow rules as described in [[https://github.com/bbatsov/clojure-style-guide][Clojure Style Guide]]. +If you see any inconsistencies with the style guide in the code, feel free to change these in a non-breaking way. + +If you've added new functions, each one must be covered with a set of tests. +For that purpose this project has special =test.fnl= module, that defines such macros as =assert*=, =assert-eq=, =assert-ne=, and =test=. +All tests must be created with the =test= macro, which automatically defines the test function and runs it afterwards. +All assertions in tests must be one with one of =assert-eq=, =assert-ne=, or =assert*= macros, as these provide human readable output in the log. + +When changing existing functions make sure that all tests pass. +If some tests do not pass, make sure that these tests are written to test this function. +If not, then, perhaps, you've broke something horribly. + +Before comitting changes you must run tests with =Make test=, and all of the tests must pass without errors. + +** Writing documentation +If you've added new code, make sure it is covered not only by tests but also with documentation. +This includes writing documentation strings directly in the code, either by using docstring feature of the language, or by adding comments which begin with =DOC:= + +Documentation uses org format because it is easy to convert it to all kinds of formats. +Please make sure to follow existing style of documentation, which can be shortly describing as: + +- One sentence per line. + This makes easier to see changes while browsing history. +- No indentation of text after headings. + This makes little sense with one sentence per line approach anyway. +- No empty lines after headings. +- Amount of empty lines in text should be: + - Single empty lines between paragraphs. + - Double empty lines before top level headings. + - Single empty lines before other headings. +- Consider using spell checking. + If you find a word not known by the dictionary, please add it to the =LocalWords= section at the bottom of the document. + +If you're not using Emacs, there are plugins for other editors of varying completeness that provide support for Org file formats. +Here are some popular ones: Atom [[https://atom.io/packages/org-mode][package]], VSCode [[https://github.com/vscode-org-mode/vscode-org-mode][plugin]], SublimeText [[https://packagecontrol.io/packages/orgmode][plugin]]. +Even without the plugin it is not hard to edit such Org files, as it is just plain text. + +** Working with Git +Check out new branch from project's main development branch. +If you've cloned this project some time ago, consider checking if your branch has all recent changes from upstream. + +Each commit must have a type, which is one of =feature=, =fix=, followed by optional scope, and a must have description after =:= colon. +For example: + +#+begin_example +fix(core macros): fix #42 +feature(tests): add more strict tests +#+end_example + +- =feature= must be used when adding new code. +- =fix= must be used when fixing existing code. + +When creating merge request consider squashing your commits at merge. +You may do this manually, or use Gitlab's "Squash commits" button. + +# LocalWords: bugfix docstring comitting VSCode SublimeText +# LocalWords: Gitlab's LocalWords |