Project:Proxy Maintainers/User Guide/Style Guide

From Gentoo Wiki
Jump to: navigation, search

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 my-ebuild.ebuild

Or C-c C-n in emacs with ebuild-mode (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}

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

  1. Unconditional deps, sorted alphabetically
  2. 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).


See also