aboutsummaryrefslogtreecommitdiffstats
path: root/COMMITSTYLE.md
blob: 85cdb78cfa72f6d8c31042884c44f5e743d99973 (plain)
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
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
Policy for commits in aports
============================

This document defines policy for organizing and titling commits for
inclusion in aports.

Glossary
---------

Definition used for the following terms.

##### Repository

Where the aport resides, it is the penultimate repository in the path of
the aport.

Example: `main/foo/APKBUILD`, `main` is the repository

##### Aport

Directory inside the repository that contains a build recipe with metadata
(APKBUILD) and auxiliary files.

The name of the directory and the value of the variable `pkgname` in the
build recipe **must** match.

Example: `main/foo/APKBUILD`, `foo` is the aport

##### Commits

Set of changes to files as recorded by git with other metadata like title,
message and an autogenerated ID.

##### Merge Request

Proposal of a set of commits to be merged into a branch of a repository.

This is what maintainers review, and what Continous Integration checks to
guarantee it won't break anything.

In Alpine Linux' aports terms this is commonly the `master` branch of the
repo. Other branches like `3.X-stable` are used to push to released versions.

Organizing
----------

Commits should be split by function and what aport they change, one commit
per aport changed, and one commit per type of change.

Commits that are related to the same aport or are closely related must be
under the same Merge Request.

Exceptions to these organization rules may apply depending on the situation,
as noted below.

Commit types
------------

Different sets of changes in a commit award a different type that has a
distinct template, rules and exceptions to follow when organizing and titling.

---

### Upgrade

Increases the value of `pkgver`, and sets the value of `pkgrel` to 0.

###### Template

- `$repository/$pkgname: upgrade to $pkgver`
  
Example: `main/foo: upgrade to 2.0.0`

###### Rules

One commit per upgraded aport.

###### Exceptions

Upgrading lots of aports that are maintained upstream in lockstep (same version
and released at the same time) can be all in the same commit

Example: KDE Plasma Framework

---

### Downgrade

Decreases the value of `pkgver`, and increases the value of `pkgrel` by 1 in 
relation to the value of `pkgrel` before the last upgrade.

###### Template

- `$repository/$pkgname: downgrade to $pkgver`

Example: `main/foo: downgrade to 1.9.8`

###### Rules

One commit per downgraded aport.

---

### Move

Moves an aport from one repository to another.

###### Template

- `$newrepository/$pkgname: move from $oldrepository`

Example: `community/foo: move from main`

###### Rules

One commit per moved aport.

---

### Rename

Renames an aport.

###### Template

- `$repository/$newpkgname: rename from $oldpkgname`

Example: `community/bar: rename from foo`

###### Rules

One commit per renamed aport.

---

### Add

Introduces a new aport.

###### Template

- `$repository/$pkgname: new aport`

Example: `testing/bar: new aport`

###### Rules

One commit per aport introduced.

---

### Remove

Removes an aport from aports altogether.

#### Template

- `$repository/$pkgname: remove`

Example: `community/baz: remove`

#### Rules

One commit per removed aport.

---

### Rebuilds

Only increasing the value of `pkgrel` by 1.

#### Template

- `$repository/$pkgname: rebuild <reason-if-exists>`

Example: `community/foo: rebuild`

#### Rules

One commit per rebuilt aport.

#### Exceptions

When various aports need to be rebuilt for the same reason the commit can
hold all `Rebuilds` but split instead by by repository.

Example: `community/*: rebuild for so:libfoo.so.2`

<!--
Missing improvements
Also missing tree-wide changes like usage of abuild-meson instead of meson
-->

---

### Other

Any set of changes not specified above falls under this type.

#### Template

If the commit changes an aport:

- `$repository/$pkgname: <action>`

If the commit changes anything else in the repository:

- `$directory_or_file: <action>`
    - If the file is inside a directory use the directory, if inside a file use the name of the file

`<action>` is what is the commit is doing. Be **short** and **direct**.

Examples:

- `main/foo: fix policy violations`
- `scripts/: enable compilation under mips64el`

#### Rules

It is **essential** to include reasoning for the changes in the body of the
commit.

Universal Title writing rules
-----------------------------

Applies to all commits, regardless of type.

### Imperative, Present Tense

Use the Present Tense and the Imperative mood

Examples:

- `main/foo: remove stale patches`
- `community/bar: patch CVE-YYYY-XXXXX`
- `testing/baz: fix policy violations`

### Lowercase, No dot

Text after the colon must start in lowercase and have no dot at the end.

### Direct, Short

Focus on **what** the commit does and use as few words as possible.

If possible also tell **why**.

Good examples:

- `main/foo: fix build under gcc-10`
    - `fix build` is **what**
    - `under gcc-10` is **why**
- `main/foo: disable support for X`
    - `disable support for X` is **what**
- `main/foo: add fish completion`
    - `add fish completion` is **what**
- `main/foo: enable on x86`
    - `enable on x86` is **what**
- `main/foo: rebuild for so:foo.so.2`
    - `rebuild` is **what**
    - `for so:foo.so.2` is **why**

They are short and concise, they tell **what** the commit did. If given
the opportunity also tell **why**.

The **how** and a clear **why** is handled by the commit body and changes.

### Assume basic knowledge, Avoid unnecessary explanations

The reader does not need to be told how the complex details of something work,
just that it was the reason the change was done.

Example:  

Don't tell the user how sonames work and how an ELF binary finds libraries
to load via the soname, just tell the soname has changed and thus a rebuild was
required.