This document defines policy for organizing and titling commits for inclusion in aports.
Definition used for the following terms.
Where the aport resides, it is the penultimate repository in the path of the aport.
Example: main/foo/APKBUILD, main is the repository
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
Set of changes to files as recorded by git with other metadata like title, message and an autogenerated ID.
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.
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.
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.
Increases the value of pkgver, and sets the value of pkgrel to 0.
$repository/$pkgname: upgrade to $pkgver
Example: main/foo: upgrade to 2.0.0
One commit per upgraded aport.
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
Decreases the value of pkgver, and increases the value of pkgrel by 1 in
relation to the value of pkgrel before the last upgrade.
$repository/$pkgname: downgrade to $pkgver
Example: main/foo: downgrade to 1.9.8
One commit per downgraded aport.
Moves an aport from one repository to another.
$newrepository/$pkgname: move from $oldrepository
Example: community/foo: move from main
One commit per moved aport.
Renames an aport.
$repository/$newpkgname: rename from $oldpkgname
Example: community/bar: rename from foo
One commit per renamed aport.
Introduces a new aport.
$repository/$pkgname: new aport
Example: testing/bar: new aport
One commit per aport introduced.
Removes an aport from aports altogether.
$repository/$pkgname: remove
Example: community/baz: remove
One commit per removed aport.
Only increasing the value of pkgrel by 1.
$repository/$pkgname: rebuild <reason-if-exists>
Example: community/foo: rebuild
One commit per rebuilt aport.
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
Adding yourself as maintainer.
$repository/$pkgname: take over maintainership
Example: community/foo: take over maintainership
One commit per aport assumed maintainership of.
Removing yourself as maintainer.
$repository/$pkgname: drop maintainership
Example: community/foo: drop maintainership
One commit per aport maintainership is removed from.
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
Any set of changes not specified above falls under this type.
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
It is essential to include reasoning for the changes in the body of the commit.
Applies to all commits, regardless of type.
Use the Present Tense and the Imperative mood
Examples:
main/foo: remove stale patchescommunity/bar: patch CVE-YYYY-XXXXXtesting/baz: fix policy violations
Text after the colon must start in lowercase and have no dot at the end.
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.
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.