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

---

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.