Project:Proxy Maintainers/User Guide/Style Guide

Proxy-maint follows QA and devmanual policies, and in addition to that, recommends some general styling guidelines. That is common within big projects who maintain a lot of packages. Rationale being common, consistent styling, and especially in proxy-maint project it makes ebuilds and metadata.xml files more readable which enables faster review times. Proxy-maint follows default skel syntax for ebuild and metadata.xml files.

Usually cosmetic issues are not a reason to reject your contribution, but if other QA issues are pointed out and asked to fix, you might be additionally asked to fix any cosmetic issues to honor our guidelines. Please work with us.

Avoid using single-char *DEPEND variable

Avoid using CDEPEND, HDEPEND and such. Instead use any definitive word instead of 1 char. For example COMMON_DEPEND, CLIENT_DEPEND, SERVER_DEPEND are good.

Any 1-character *DEPEND should be reserved for internal portage usage. When such variable is introduced, we don't have to start updating multiple ebuilds, because we've done the preventive work already.

See Future EAPI how portage might start using such variables in future.

Note
With EAPI-7 and introduction of BDEPEND it's rarer having to use your own *DEPEND variable.

Clean, compact, readable metadata.xml

Minimize vertical whitespace:

FILE metadata.xmlBAD

<name>
  Foo Bar
</name>
<email>
  foo@b.ar
</email>

Use:

FILE metadata.xmlGOOD

<name>Foo Bar</name>
<email>foo@b.ar</email>

Where line length doesn't exceed 100 chars. Remember indentation.

Descriptive text

We don't put dot (.) at the end of descriptive texts like these:

DESCRIPTION field in an .ebuild file
<flag name="xyz">Text</flag> in metadata.xml

One empty line below EAPI= line

We try to follow the default skel format whenever possible. If in doubt, use

user $vim packagename-1.2.3.ebuild

Or C-c C-n in emacs with ebuild-mode (M-x ebuild-mode-skeleton) to make an empty ebuild with correct structure. For those not using vim or emacs, skel.ebuild provides documented skeleton file.

Plaintexting ${PN} in SRC_URI

We like to plaintext ${PN} variable in SRC_URI and REPO_URI, because it's not a changeable variable and makes copy-pasting from your ebuild easier, or using external tools such as grep.

See also PG 0103, similar rationale applies here.

Sorting dependencies

Unconditional deps, sorted alphabetically
Conditional deps, sorted by USE flag, also alphabetically

CODE Example of a *DEPEND variable

app-misc/package
>=dev-cpp/other-package-2.0
dev-cpp/package
dev-libs/mylib:=
dev-perl/Pod-LaTeX
dev-vcs/git[curl]
sys-process/toolone
bluetooth? ( net-wireless/bluez )
gnome-keyring? ( app-crypt/libsecret )
zip? (
	app-arch/lzip
	app-arch/zstd
)

Handling multi live/release ebuilds

Live ebuilds are not mandatory, but if you'd like to provide them, use structure such as this:

CODE

if [[ ${PV} == *9999 ]]; then
	inherit git-r3
	EGIT_REPO_URI="https://github.com/author/package.git"
else
	SRC_URI="https://github.com/author/package/archive/v${PV}.tar.gz -> ${P}.tar.gz"
	KEYWORDS="~amd64 ~arm ~arm64 ~x86"
fi

Use if [[ ${PV} == 9999 ]]; then instead of case ... esac. It's cleaner, simpler, shorter and proven to work with in every case (different package manager implementations for example).
Do not specify KEYWORDS inside "9999" block, as it breaks the ekeyword tool (PG 0105).
You can also use *9999 for "pre-live" releases, like 1.2.9999, or -99999999 packages.