1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
|
#+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 out 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.
Consider checking test coverage with =make luacov= and rendering it with your preferred reporter.
Makefile also has =luacov-console= target, which can be used to see coverage of lua code directly in the terminal.
** 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
|