aboutsummaryrefslogtreecommitdiffstats
path: root/COMMITSTYLE.md
diff options
context:
space:
mode:
authorLeo <thinkabit.ukim@gmail.com>2020-11-13 15:13:18 -0300
committerLeo <thinkabit.ukim@gmail.com>2020-11-18 03:10:14 +0000
commit0b70974e074fa6d961ceded2428b99ddc2cc0ef4 (patch)
treea6e098ca2b8dde9c0a6945c6d7070ae197b246f7 /COMMITSTYLE.md
parent9d74e77219443a4f089328f3017ac115bd60a7ab (diff)
downloadaports-0b70974e074fa6d961ceded2428b99ddc2cc0ef4.tar.gz
aports-0b70974e074fa6d961ceded2428b99ddc2cc0ef4.tar.bz2
aports-0b70974e074fa6d961ceded2428b99ddc2cc0ef4.tar.xz
COMMITSTYLE.md: formalize informal rules on organizing and titling commits
Diffstat (limited to 'COMMITSTYLE.md')
-rw-r--r--COMMITSTYLE.md277
1 files changed, 277 insertions, 0 deletions
diff --git a/COMMITSTYLE.md b/COMMITSTYLE.md
new file mode 100644
index 0000000000..250aeddaf4
--- /dev/null
+++ b/COMMITSTYLE.md
@@ -0,0 +1,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.