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
| | =======
Hacking
=======
We’re thrilled to have you here! Your interest in making olang the most
exceptional and straightforward language ever is greatly appreciated.
In this document, we’ll outline how you can begin contributing to olang.
First and foremost, clone the project if you haven’t done so already.
.. code-block:: sh
git clone https://git.sr.ht/~johnnyrichard/olang
Dependencies
============
The olang compiler is crafted in C. To build the project, you’ll require
merely three dependencies: **make**, **gcc** (version 11 or higher), and
**clang-format** (version 14 or higher).
As an optional step, you can install **sphinx** to refresh this documentation.
Code style
==========
Instead of delineating every element of our coding style, we have adopted the
use of **clang-format** to enforce the olang code style. Please refer to the
linter section below for guidance on its application.
Linter
------
Checking for linter issues:
.. code-block:: sh
make linter
Most of the common code style mistakes are fixed by:
.. code-block:: sh
make linter-fix
.editorconfig
-------------
We also provide a **.editorconfig** file at project's root. Follow
https://editorconfig.org/ to learn how to make it work with your favorite
editor.
Testing
=======
There are two layers of tests **integration** and **unit**. The integration
test is going to execute the **0c** compiler and check if the generated binary
acts as expected. Unit tests will test C functions.
For both unit and integration we use **munit** framework: https://nemequ.github.io/munit/.
To execute tests you can execute:
.. code-block:: sh
make check
Submitting a patch
==================
Before submit a patch, ensure your code follows our coding style and is
well-tested. After that, you're good to follow the steps bellow.
Step 1: Commit your changes
---------------------------
Begin by committing your modifications with a detailed and significant commit
message. We take great pleasure in maintaining a record of our changes over
time. Skeptical? Execute a **git log** command and admire the well-documented
history we’ve created so far.
But it isn't all about personal preference. We use a email-driven workflow
to propose our changes, meaning the commit message you write is the email the
olang maintainers will get. I won’t go into the perks of the email-driven
workflow here, but you can check it out at
https://drewdevault.com/2018/07/02/Email-driven-git.html.
Best practices
^^^^^^^^^^^^^^
#. Write single-purpose commits.
#. Write a meaningful commit message.
#. Every commit must be production ready.
- If the tests or the linter fail, you should not create a fix commit.
Instead, you should amend the commit that caused the issue and then resend
the patchset.
Step 2: Create your patch
-------------------------
You can create a patch using the command:
.. code-block:: sh
git format-patch --cover-letter -M origin/main -o outgoing/
Step 3: Write a cover letter:
-----------------------------
The command above generates a **outgoing/0000-cover-letter.patch** file.
The cover letter is like a pull request description on Github. Replace the
\*\*\* SUBJECT HERE \*\*\* with the patchset title and the
\*\*\* BLURB HERE \*\*\* with a synopsis of your changes.
If you are sending a single-commit patch you can remove the **--cover-lette**
argument from **git format-patch** and skip this step.
Step 4: Submit your patch
-------------------------
Make sure you have configured your **git send-email**. You can learn how to
configure it here:
https://git-scm.com/docs/git-send-email#_examples
Once you have everything set you just need to send the patch over our
mailing list.
.. code-block:: sh
git send-email outgoing/* --to=~johnnyrichard/olang-devel@lists.sr.ht
The review process
------------------
Upon submission, you’ll receive an automated email from our pipeline. If the
check is successful, the olang maintainers will review your patch.
Subsequently, you’ll receive an email indicating whether your patch has been
approved, requires changes, or has been rejected.
Submitting changes in a patchset
--------------------------------
If your patchset requires any modifications, you’ll have to submit a new
version of your patch. The submission process remains unchanged, except for the
addition of the version argument to the **git format-patch** command.
.. code-block:: sh
git format-patch --cover-letter -M origin/main -o outgoing/ -v2
After send a new email with **git send-email**.
----
Thanks again and happy hacking!
|