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 repository.
Example: community/*: rebuild for so:libfoo.so.2
Addition of maintainership
Adding yourself as maintainer.
Template
$repository/$pkgname: take over maintainership
Example: community/foo: take over maintainership
Rules
One commit per aport assumed maintainership of.
Removal of maintainership
Removing yourself as maintainer.
Template
$repository/$pkgname: drop maintainership
Example: community/foo: drop maintainership
Rules
One commit per aport maintainership is removed from.
Exceptions
When removing maintainership from all aports you maintain, the commit can hold all maintainership removals but instead be split by repository.
Example: community/*: drop maintainership
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 violationsscripts/: 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 patchescommunity/bar: patch CVE-YYYY-XXXXXtesting/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-10fix buildis whatunder gcc-10is why
main/foo: disable support for Xdisable support for Xis what
main/foo: add fish completionadd fish completionis what
main/foo: enable on x86enable on x86is what
main/foo: rebuild for so:foo.so.2rebuildis whatfor so:foo.so.2is 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.