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
| | % 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.
``` {.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:
``` {.sh}
make linter
```
Most of the common code style mistakes are fixed by:
``` {.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:
``` {.sh}
make check
```
Submitting a patch
------------------
All contributors are required to "sign-off" their commits (using git commit -s)
to indicate that they have agreed to the [Developer Certificate of
Origin](https://developercertificate.org/).
Before submit the patch, ensure the 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
1. Write single-purpose commits.
2. Write a meaningful commit message.
3. 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:
``` {.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-letter** 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.
``` {.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.
``` {.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!
|