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.