ref: refs/heads/master viuavm/CONTRIBUTING.markdown -rw-r--r-- 5.5 KiB View raw
                                                                                
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
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
# Viua VM contributor guidelines

So, you want to help out with development, or just see what the VM can do.
Either way - that's great.
This document will get you started.

----

## Development setup

Here you can find information about development setup required to compile, test, and
develop the VM.


### Tools

* `g++`: GNU Compiler Collection's C++ compiler version 6.0 or later
* `clang++`: clang C++ compiler version 3.9.1 or later,
* `python`: Python programming language 3.x for test suite (optional),
* `valgrind`: for memory leak testing (optional; by default enabled, disabling required setting `MEMORY_LEAK_CHECKS_ENABLE` variable in `tests/tests.py` to `False`),

Other C++17 capable compilers may work but testing is only performed for G++ and Clang++.

The development environment is also assumed to have the usual \*NIX tools (awk, sed, xargs, etc.) available.


### Operating system

Testing is regularly performed only on Linux.
Compilation on on various BSD distributions should also work.
Compilation on other operating systems is not tested, but contributors with access to
Microsoft, Apple, or other exotic operating systems are welcome to try and compile the code, to see if it runs.


### Typical "from clone to first run"

```
$ git clone --branch devel --recursive git@github.com:marekjm/viuavm.git
$ cd viuavm/
$ make -j 4
$ make test     # this assumes that you have Python 3.x and Valgrind installed
```

If the above sequence of commands can be run without problems on your system then
you're all set.

*Note:* the last command - `make test` - may run for several minutes, depending on the speed of your hardware.


### Development scripts

In the `scripts/` directory, you can find scripts that are used during development of Viua.

----


## Git workflow

Each feature and fix is developed in a separate branch.
Bugs which are discovered during development of a certain feature,
may be fixed in the same branch as their parent issue.
This is also true for small features.

**Branch structure:**

- `master`: master branch - contains stable, working version of VM code,
- `devel`: development branch - all fixes and features are first merged here,
- `issue/<number>/<slug>` or `issue/<slug>`: for issues (both enhancement and bug fixes),

----


## Patch submissions

Patch submissions and issue reports are both welcome.
Appropriate interface for reporting is the Github issues page.

Rememeber to provide appropriate test cases with code patches you submit.
It will be appreciated and will make the merge process faster.
If you're fixing a bug:

- write a test that will catch the bug should it resurface
- put comments in the code sample your test uses

If you're implementing a feature:

- provide a positive test (i.e. feature working as intended and performing its function)
- provide a negative test (i.e. feature generating an error)
- put comments in the code samples the tests use

In both cases your code must pass the tests on both x86\_64 and 64 bit ARM (if you don't have an ARM CPU around
mention it when submitting a pull request and I'll test on ARM myself).
Your code must also run clean under Valgrind, which implies:

- no memory leaks
- no hangs due to multithreading
- no unprotected reads/writes to memory

Remember - if your code normally runs OK, but behaves strangely under Valgrind it's most
probably a sign that there's a problem with your code.


### Vulnerabilities

Vulnerabilities are considered bugs, and the standard way of submission applies.
A GitHub issue should be opened with a description of how to exploit the VM, and
a possible fix preventing the exploit.


### Coding standard

When submitting a patch make sure that it is formatted according to the coding standard:
It is described [here](CODING_STYLE.markdown).

----

## Suggested contributions


**Documentation**

As always, the documentation is lacking.
If you're interested in writing documentation have a go at it.


**Code samples**

> Talk is cheap, show me the code.

The VM will be no good, if no code runs on it.
If you have written something that runs on the VM (a short program solving your problem, or
a Rosetta Code task) submit a pull request.
Your sample should contain appropriate copyright notice pointing to you, and
be published under GNU GPL v3 or any later version of the GPL.


**Data structures**

Viua uses only the C++ standard library data structures.
However, if you are capable of writing efficient, reliable, concurrent data structures feel welcome
to share your knowlegde and experience, and improve the VM.

Most sought-after would be:

- multiple-producer single-consumer queue (for message queues),
- data structure for mapping types to their ancestors (e.g. map from string to vector of strings),
- multi-version map (for storing multiple versions of loaded bytecode modules for code hot-swapping)

If you have other ideas, feel free to suggest them.

Note that *all* data structures used by the VM kernel *must* support parallel access so either use locks, or
atomic operations but ensure that your data structure is safe to use in parallel environment.


**Bytecode format**

Currently, debugging information embedded in bytecode is limited.
If you have an idea how to embed debugging symbols in bytecode, and
want to have a go at implementing such a functionality feel free to.


**Overall hardening**

If you can set-up Coverity (I seem unable to), it would be a great help.
Otherwise, if you can spot memory access bugs, multithreading bugs, use ASan, TSan, or
other sanitisers - don't hesitate and attack the VM as hard as you can.
After all, the more bugs you find - the more bugs will be fixed.