[gentoo-commits] data/glep:master commit in: /

[Michał Górny]

commit:     90abb55d4eed07b5caaaf62e9cbe3d077d279ef5
Author:     Michał Górny <mgorny <AT> gentoo <DOT> org>
AuthorDate: Mon May 31 08:12:12 2021 +0000
Commit:     Michał Górny <mgorny <AT> gentoo <DOT> org>
CommitDate: Mon May 31 08:12:12 2021 +0000
URL:        https://gitweb.gentoo.org/data/glep.git/commit/?id=90abb55d

glep-0082: initial draft for layout.conf GLEP

Signed-off-by: Michał Górny <mgorny <AT> gentoo.org>

 glep-0082.rst | 294 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 294 insertions(+)

diff --git a/glep-0082.rst b/glep-0082.rst
new file mode 100644
index 0000000..8a1094b
--- /dev/null
+++ b/glep-0082.rst
@@ -0,0 +1,294 @@
+---
+GLEP: 82
+Title: Repository configuration file (layout.conf)
+Author: Michał Górny <mgorny@g.o>
+Type: Standards Track
+Status: Draft
+Version: 1.0
+Created: 2021-05-19
+Last-Modified: 2021-05-31
+Post-History: 2021-05-19
+Content-Type: text/x-rst
+---
+
+Abstract
+========
+
+The ``metadata/layout.conf`` file format is specified as used by Portage
+and pkgcore.  A standard set of configuration keys is described
+including the keys currently used in the Gentoo repository.
+
+
+Motivation
+==========
+
+The ``metadata/layout.conf`` file was first added to the Gentoo
+repository in Oct 2011, to facilitate setting of hashes used
+in Manifest2 files.  In Mar 2012, it was used to indicate the transition
+to the new ``md5-dict`` cache format.  In Jul 2013, it started being
+used to indicate the repository's masters and effectively became
+obligatory for all repositories.
+
+Today, ``layout.conf`` is used for various repository configuration
+knobs that can be expressed as simple values and therefore
+do not justify adding new files to the repository.  This primarily
+involves the configuration of development tools but also includes a few
+keys relevant to the behavior of the package manager.
+
+However, ``layout.conf`` is currently not covered by any formal
+specification.  The PMS neglects its existence entirely, and the keys
+used are roughly defined by their first use of Portage or pkgcore.
+This GLEP aims to overcome this by providing a formal specification
+for the file, as well as an up-to-date list of permitted configuration
+keys.
+
+
+Specification
+=============
+
+layout.conf file format
+-----------------------
+
+Every ebuild repository must contain a ``metadata/layout.conf`` file.
+The file uses a line-oriented key-value format::
+
+    # comments are allowed
+    key = value
+    key2 = value2
+
+Lines starting with a hash sign (``#``) represent comments and are
+ignored, as are lines consisting entirely of whitespace.
+
+Key can be any string and must not contain spaces.  The exact form
+of value depends on the key.  For some keys, the value is permitted
+to contain spaces, and it must not be quoted.  In some cases an empty
+value is permitted.  The whitespace between the elements is optional
+and is ultimately stripped.  Every key must occur no more than once
+in the file.
+
+
+Configuration keys
+------------------
+
+This GLEP specifies a number of standard configuration keys.  New keys
+may be added to it in the future.  It is strongly recommended that any
+new keys are added to the specification before being used.
+
+The package manager can implement a subset of the listed keys.  Unknown
+keys should be ignored.
+
+
+The following keys must be present in a ``layout.conf`` file:
+
+masters = <space-separated repository names>
+  Specifies the master repositories of this repository.  For stand-alone
+  repositories, this must be set to an empty value.  Otherwise, it can
+  list one or more repositories, separated by spaces.  This key must
+  be specified.
+
+  Examples::
+
+      # most common case
+      masters = gentoo
+      # stand-alone repository
+      masters =
+      # multiple masters
+      masters = gentoo python
+
+
+The following keys are optional:
+
+manifest-hashes = <space-separated hash names>
+  Specifies the list of hashes that should be used for new distfiles
+  in the Manifest files.  The development tools may create a subset
+  of the specified hashes if it is not updating the checksums for
+  the specified distfile, or does not support the hash in question.
+  The hash names are specified in GLEP 74.  [#GLEP74]_  The default
+  set of hashes is implementation-defined.
+
+  Example::
+
+      manifest-hashes = BLAKE2B SHA512
+
+manifest-required-hashes = <space-separated hash names>
+  Specifies the list of hashes that must be used in Manifest files.
+  The development tools must support all the hashes listed there,
+  and update distfile checksums to use these hashes (refetching
+  if necessary).  This must be a subset of manifest-hashes.  If not
+  specified, all hashes from manifest-hashes (or the default set)
+  are considered required.
+
+use-manifests = ``strict``, ``true`` or ``false``
+  Indicates the policy for creating and using Manifest files.  If set
+  to ``strict``, Manifest files are created and files are required to
+  match digests found in Manifests.  If set to ``true``, Manifests
+  are created but digest mismatches are ignored.  If set to ``false``,
+  Manifests are not used at all.  The default is ``strict``.
+
+update-changelog = ``true`` or ``false``
+  Indicates whether the development tools should write ChangeLog files.
+  The default is ``false``.
+
+cache-formats = <space-separated format names>
+  Specifies one or more cache formats used by the repository.
+  The currently defined values are ``pms`` for the original format
+  specified in the PMS and ``md5-dict`` for the md5-dict format
+  introduced in Portage 2.2.0_alpha68.  The default is
+  implementation-defined.
+
+  Examples::
+
+      # modern repo
+      cache-formats = md5-dict
+      # backwards compatibility case
+      cache-formats = md5-dict pms
+
+eapis-deprecated = <space-separated EAPI names>
+  Specifies one or more EAPIs that are to be considered deprecated
+  by the development tools for use in ebuilds, i.e. their use should
+  trigger a warning.  If not specified, no EAPIs are deprecated.
+
+  Example::
+
+      eapis-deprecated = 0 1 2 3 4
+
+eapis-banned = <space-separated EAPI names>
+  Specifies one or more EAPIs that are to be considered banned
+  by the development tools for use in ebuilds, i.e. their use should
+  be blocked.  If not specified, no EAPIs are banned.
+
+repo-name = <string>
+  Specifies the repository name.  If specified, it must be equal
+  to the contents of ``profiles/repo_name``.  If not specified,
+  it defaults to the same value.  Discouraged.
+
+aliases = <space-separated names>
+  Specified one or more additional names that can be used to reference
+  the repository (e.g. in repository dependencies).  If not specified,
+  no aliases are defined.
+
+  Example::
+
+      # gen2 is a fork of Gentoo that can be used in place of the Gentoo
+      # repository
+      repo-name = gen2
+      aliases = gentoo
+
+thin-manifests = ``true`` or ``false``
+  If enabled, Manifest files in the package directory must contain only
+  ``DIST`` entries.  If disabled, Manifest files in the package
+  directory must list digests for all files found in the package
+  directory and the files directory.  The default is ``false``.
+
+sign-commits = ``true`` or ``false``
+  Indicates whether git commits are to be signed (using ``git commit
+  --gpg-sign``.  The default is ``false``.
+
+sign-manifests = ``true`` or ``false``
+  Indicates whether individual package Manifests should be PGP-signed.
+  Note that this refers to the historical behavior of signing individual
+  Manifests, not the GLEP 74 behavior of signing the top-level Manifest.
+  [#GLEP74]_  The default is ``true`` if PGP signing is configured.
+
+properties-allowed = <space-separated property tokens>
+  Specifies the list of ``PROPERTIES`` tokens that are permitted
+  to be used in ebuilds.  If present, the development tools should issue
+  a warning if ``PROPERTIES`` contains any tokens that are not listed
+  here.  If not specified, all tokens are permitted.
+
+  Example::
+
+      properties-allowed = live
+
+restrict-allowed = <space-separated restrict tokens>
+  Same as properties-allowed, except for ``RESTRICT``.
+
+profile-formats = <space-separated format names>
+  Specifies the format used by profiles and/or extensions to it.
+  The default is ``pms`` indicating the format specified in the PMS.
+  Other values are implementation-defined.
+
+  Examples::
+
+      profile-formats = portage-1
+      profile-formats = portage-2 profile-set
+
+
+Complete example
+----------------
+
+The following is an example configuration for a git repository with
+Gentoo set as a master::
+
+    masters = gentoo
+
+    # git: do not use ChangeLog, use thin, unsigned Manifests
+    update-changelog = false
+    thin-manifests = true
+    sign-manifests = false
+
+    # force the new md5-dict cache format
+    cache-formats = md5-dict
+
+
+Rationale
+=========
+
+This GLEP is written almost 10 years after ``layout.conf`` was
+originally introduced.  This made it necessary to write it in such a way
+that both the modern and historical implementations in Portage
+and pkgcore, as well as the use in the Gentoo repository
+and a reasonably large subset of the other repositories would remain
+compliant.
+
+The historical default of assuming ``masters = gentoo`` when unspecified
+is omitted as it is not portable and verbosely deprecated for many
+years in Portage.  All repositories are required to explicitly specify
+their masters, or an empty value if they are stand-alone.
+
+The default for Manifest hashes and cache formats are left to be
+implementation-defined, as the defaults changed over time and do not
+match between package managers.  In particular, Portage attempts to
+autodetect the cache format currently used in a given repository.
+
+The repo-name key has been originally added as an alternative to
+``profiles/repo_name``.  However, the latter file is still required
+for PMS compliance.  Furthermore, given that it is much easier to parse,
+there seems to be no appealing reason to work towards replacing that
+file.  This means that for all practical reasons, the repo-name key
+is redundant and is listed here for completeness only.
+
+The profile-formats key has been introduced to permit Portage-specific
+extensions to the profile directory without having to introduce custom
+EAPIs.  The exact extensions are considered outside the scope of this
+specification.
+
+
+Backwards Compatibility
+=======================
+
+The existing implementations found in Portage and pkgcore conform
+to this specification, so does the ``metadata/layout.conf`` file
+found in the Gentoo repository.
+
+
+Reference Implementation
+========================
+
+The support for ``metadata/layout.conf`` is already a part of Portage
+and pkgcore.
+
+
+References
+==========
+
+.. [#GLEP74] GLEP 74: Full-tree verification using Manifest files
+   (https://www.gentoo.org/glep/glep-0074.html)
+
+
+Copyright
+=========
+
+This work is licensed under the Creative Commons Attribution-ShareAlike 4.0
+International License. To view a copy of this license, visit
+https://creativecommons.org/licenses/by-sa/4.0/.