From 9ca537f5c1a362d001dc7c0e6ce03994e07ea68b Mon Sep 17 00:00:00 2001 From: Jason Tibbitts Date: Jan 09 2019 19:49:27 +0000 Subject: Convert Naming guidelines to semantic linebreaks. --- diff --git a/guidelines/modules/ROOT/pages/Naming.adoc b/guidelines/modules/ROOT/pages/Naming.adoc index 98d2186..ba34076 100644 --- a/guidelines/modules/ROOT/pages/Naming.adoc +++ b/guidelines/modules/ROOT/pages/Naming.adoc @@ -3,13 +3,18 @@ == Versioning guidelines have moved -This document previously contained information on both naming and versioning. The versioning guidelines are now at Packaging:Versioning. +This document previously contained information on both naming and versioning. +The versioning guidelines are now at Packaging:Versioning. == Common Character Set for Package Naming -While Fedora is an international community, for consistency and usability, there needs to be a common character set for package naming. +While Fedora is an international community, +for consistency and usability, +there needs to be a common character set for package naming. -Specifically, all Fedora packages must be named using only the following ASCII characters. These characters are displayed here: +Specifically, +all Fedora packages must be named using only the following ASCII characters. +These characters are displayed here: .... abcdefghijklmnopqrstuvwxyz @@ -17,39 +22,57 @@ ABCDEFGHIJKLMNOPQRSTUVWXYZ 0123456789-._+ .... -But do check #Separators for additional restrictions on using the `+-._++` characters. +But do check #Separators for additional restrictions +on using the `+-._++` characters. === General Naming -Package names SHOULD be in lower case and use dashes in preference to -underscores. You can take some cues from the name of the upstream tarball, -the project name from which this software came, and the name which has been used for this -package by other distributions/packagers in the past. You can also request -guidance from the upstream developers. Do not just blindly follow those -examples, however, as package names SHOULD strive to be consistent within -Fedora more than consistent between distributions. +Package names SHOULD be in lower case +and use dashes in preference to underscores. +You can take some cues from the name of the upstream tarball, +the project name from which this software came, +and the name which has been used for this package +by other distributions/packagers in the past. +You can also request guidance from the upstream developers. +Do not just blindly follow those examples, however, +as package names SHOULD strive to be consistent +within Fedora more than consistent between distributions. Additionally, it is possible that the upstream name does not fall into the -link:#CommonCharacterSet[ Common Character Set] . If this is the case, refer to: +link:#CommonCharacterSet[ Common Character Set] . +If this is the case, refer to: link:#Transliteration[ When Upstream Naming is outside of the specified character set] . -Also remember to check whether the type of package you are packaging has -specific rules for naming. Packaging:NamingGuidelines#Font_Packages[Font -packages] and the various sorts of +Also remember to check whether +the type of package you are packaging +has specific rules for naming. +Packaging:NamingGuidelines#Font_Packages[Font packages] +and the various sorts of Packaging:NamingGuidelines#Addon_Packages_.28General.29[addon packages], for instance. === Separators -When naming packages for Fedora, the maintainer MUST use the dash '-' as the delimiter for name parts. The maintainer MUST NOT use an underscore '_', a plus '+', or a period '.' as a delimiter. Version numbers used in compat libraries do not need to omit the dot '.' or change it into a dash '-' (see link:#MultiplePackages[ Multiple packages with the same base name] for more info on this case). +When naming packages for Fedora, +the maintainer MUST use the dash '-' as the delimiter for name parts. +The maintainer MUST NOT use an underscore '_', a plus '+', or a period '.' as a delimiter. +Version numbers used in compat libraries do not need to omit the dot '.' +or change it into a dash '-' +(see link:#MultiplePackages[ Multiple packages with the same base name] +for more info on this case). There are a few exceptions to the no underscore '_' rule. -* httpd, pam, and SDL addon packages are excluded, refer to "'''link:#AddonHttpdPamSDL[ Addon Packages (httpd, pam and SDL)] '''". -* packages that are locale specific, and use the locale in the name are excluded, refer to "'''link:#AddonLocale[ Addon Packages (locale)] '''". -* Compat packages where the base package name ends in a digit. refer to "*link:#MultiplePackages[ Multiple packages with the same base name]*" -* packages where the upstream name naturally contains an underscore are excluded from this. Examples of these packages include: +* httpd, pam, and SDL addon packages are excluded, +refer to "'''link:#AddonHttpdPamSDL[ Addon Packages (httpd, pam and SDL)] '''". +* packages that are locale specific, +and use the locale in the name are excluded, +refer to "'''link:#AddonLocale[ Addon Packages (locale)] '''". +* Compat packages where the base package name ends in a digit. +refer to "*link:#MultiplePackages[ Multiple packages with the same base name]*" +* packages where the upstream name naturally contains an underscore +are excluded from this. Examples of these packages include: .... arptables_jf @@ -69,45 +92,105 @@ If in doubt, ask on devel@lists.fedoraproject.org. === When Upstream Naming is outside of the specified character set -Fedora recognizes that the task of converting text to the specified ASCII character set (aka transliteration) is difficult. Accordingly, when the upstream name is outside of the specified ASCII character set, the Fedora package maintainer SHOULD first contact the upstream for that software and ask them for a transliteration of the name for Fedora to use. +Fedora recognizes that the task of converting text +to the specified ASCII character set (aka transliteration) is difficult. +Accordingly, when the upstream name is outside of the specified ASCII character set, +the Fedora package maintainer SHOULD first contact the upstream for that software +and ask them for a transliteration of the name for Fedora to use. -If (and only if) the upstream is unable, unwilling, or unavailable to provide a transliterated name, the Fedora packager must choose to either perform their own transliteration, or withdraw the package from consideration in Fedora. +If (and only if) the upstream is unable, +unwilling, or unavailable +to provide a transliterated name, +the Fedora packager must choose +to either perform their own transliteration, +or withdraw the package from consideration in Fedora. -When deciding how to transliterate a package name, the Fedora packager SHOULD look to see what (if any) other distributions have done for that package's name, and take that into account. +When deciding how to transliterate a package name, +the Fedora packager SHOULD look to see what (if any) +other distributions have done for that package's name, +and take that into account. === Extra Provides -Transliterated packages MAY Provide: the original, non-transliterated name, but are not required to do so. +Transliterated packages MAY Provide: +the original, non-transliterated name, +but are not required to do so. == Conflicting Package Names -Conflicting package names, even if they differ by case alone, are not allowed. Please see Packaging:Conflicts#Conflicting_Package_Names[Packaging:Conflicts#Conflicting Package Names] for more details. +Conflicting package names, +even if they differ by case alone, +are not allowed. +Please see +Packaging:Conflicts#Conflicting_Package_Names[Packaging:Conflicts#Conflicting Package Names] +for more details. == Multiple packages with the same base name -For many reasons, it is sometimes advantageous to keep multiple versions of a package in Fedora to be installed simultaneously. When doing so, the package name MUST reflect this fact. One package SHOULD use the base name (with no version information). All other packages derived from it MUST include the base name suffixed by either: +For many reasons, it is sometimes advantageous +to keep multiple versions of a package in Fedora +to be installed simultaneously. +When doing so, the package name MUST reflect this fact. +One package SHOULD use the base name +(with no version information). +All other packages derived from it MUST include the base name +suffixed by either: * The package version, which SHOULD include the periods present in the original version. -** If the base package name ends with a digit, a single underscore ("_") MUST be appended to the name, and the version MUST be appended to that, in order to avoid confusion over where the name ends and the version begins. -** If the base package name does not end with a digit, the version MUST be directly appended to the package name with no intervening separator. -* a hyphen ("-") followed by a descriptive suffix such as "stable" which provides some indication as to the nature of the packaged version. +** If the base package name ends with a digit, +a single underscore ("_") MUST be appended to the name, +and the version MUST be appended to that, +in order to avoid confusion over where the name ends and the version begins. +** If the base package name does not end with a digit, +the version MUST be directly appended to the package name with no intervening separator. +* a hyphen ("-") followed by a descriptive suffix +such as "stable" +which provides some indication +as to the nature of the packaged version. *Examples:* -* The python-sqlalchemy package occasionally has multiple versions in Fedora for backwards compatibility. The most current version of python-sqlalchemy is named `+python-sqlalchemy+` and an older supported version is `+python-sqlalchemy0.5+`. No delimiter is used in this situation. -* The most current version of the v8 package is named `+v8+`. In order to package version "3.13", the package MUST be named `+v8_3.13+`. - -Please also note that strings such as "-latest" can often become misleading over time if the package (in *all* active Fedora releases) is not kept updated with the latest upstream version. +* The python-sqlalchemy package occasionally has multiple versions in Fedora +for backwards compatibility. +The most current version of python-sqlalchemy is named +`+python-sqlalchemy+` +and an older supported version is +`+python-sqlalchemy0.5+`. +No delimiter is used in this situation. +* The most current version of the v8 package is named `+v8+`. +In order to package version "3.13", +the package MUST be named `+v8_3.13+`. + +Please also note that strings such as "-latest" +can often become misleading over time +if the package (in *all* active Fedora releases) +is not kept updated with the latest upstream version. === Documentation Packages with Embedded OS versioning -Documentation packages (as approved by the Fedora Documentation Project) can be named with the OS version number in the package name to allow parallel installation of multiple versions, in cases where the documentation is specific to a release of Fedora and there is value in having multiple versions simultaneously installed. +Documentation packages +(as approved by the Fedora Documentation Project) +can be named with the OS version number in the package name +to allow parallel installation of multiple versions, +in cases where the documentation is specific to a release of Fedora +and there is value in having multiple versions simultaneously installed. == Case Sensitivity -In Fedora packaging, the maintainer uses their best judgement when considering how to name the package. While case sensitivity is not a mandatory requirement, case SHOULD only be used where necessary. Keep in mind to respect the wishes of the upstream maintainers. If they refer to their application as "ORBit", you SHOULD use "ORBit" as the package name, and not "orbit". However, if they do not express any preference of case, you SHOULD default to lowercase naming. + - + -The exception to this is for perl module packaging. The CPAN Group and Type SHOULD be capitalized in the name, as if they were proper nouns . (Refer to '''link:#AddonPerl[ Addon Packages (perl modules)] ''' for details.) +In Fedora packaging, the maintainer uses their best judgement when considering how to name the package. +While case sensitivity is not a mandatory requirement, +case SHOULD only be used where necessary. +Keep in mind to respect the wishes of the upstream maintainers. +If they refer to their application as "ORBit", +you SHOULD use "ORBit" as the package name, +and not "orbit". +However, if they do not express any preference of case, +you SHOULD default to lowercase naming. + +The exception to this is for perl module packaging. +The CPAN Group and Type SHOULD be capitalized in the name, +as if they were proper nouns. +(Refer to '''link:#AddonPerl[ Addon Packages (perl modules)] ''' for details.) == Renaming/replacing existing packages @@ -115,18 +198,29 @@ See: Packaging:Guidelines#Renaming.2FReplacing_Existing_Packages == Documentation Subpackages -Large documentation files SHOULD go in a subpackage. This subpackage must be named with the format: `+%{name}-doc+` . -The definition of large is left up to the packager's best judgement, but is not restricted to size. Large can refer to either size or quantity of files. +Large documentation files SHOULD go in a subpackage. +This subpackage must be named with the format: `+%{name}-doc+` . +The definition of large is left up to the packager's best judgement, +but is not restricted to size. +Large can refer to either size or quantity of files. == Font Packages -Packages containing fonts must be named *[foundryname-]projectname[-fontfamilyname]-fonts*, in lowercase. For a full explanation, see Packaging/FontsPolicy#Naming. +Packages containing fonts must be named +*[foundryname-]projectname[-fontfamilyname]-fonts*, +in lowercase. +For a full explanation, see Packaging/FontsPolicy#Naming. == Addon Packages -If a package is considered an "addon" package that enhances or adds functionality to an existing Fedora package without being useful on its own, its name SHOULD reflect this fact. + - + -The new package ("child") SHOULD prepend the "parent" package in its name, in the format: `+%{parent}-%{child}+`. +If a package is considered an "addon" package +that enhances or adds functionality +to an existing Fedora package +without being useful on its own, its name SHOULD reflect this fact. + +The new package ("child") SHOULD prepend +the "parent" package in its name, +in the format: `+%{parent}-%{child}+`. *Examples:* @@ -137,16 +231,27 @@ python3-twisted (the twisted module for python3, relies on python3) xmms-cdread (direct cd read functionality for xmms, relies on xmms) .... -When the addon package is a language binding, note that the language itself is always the parent. Thus, a lua binding for the "randomdb" database would be `+lua-randomdb+`, not `+randomdb-lua+`. Also note that some packages may have grandfathered names using the opposite ordering. +When the addon package is a language binding, +note that the language itself is always the parent. +Thus, a lua binding for the "randomdb" database would be +`+lua-randomdb+`, +not `+randomdb-lua+`. +Also note that some packages may have grandfathered names +using the opposite ordering. -There are some exceptions to this general addon package naming policy, and they are noted below. + +There are some exceptions to this general addon package naming policy, +and they are noted below. === httpd, pam, and SDL -Packages that rely on Apache httpd, pam, or SDL as a parent use a slightly different naming scheme. -pam and SDL addons use the format: `+%{parent}_%{child}+`, with an underscore "_" as a delimiter. -Apache httpd addons use the format: `+mod_%{child}+`, with an underscore "_" as a delimiter. -This naming scheme is usually the same as used for the source tarball name. + +Packages that rely on Apache httpd, pam, or SDL +as a parent use a slightly different naming scheme. +pam and SDL addons use the format: `+%{parent}_%{child}+`, +with an underscore "_" as a delimiter. +Apache httpd addons use the format: `+mod_%{child}+`, +with an underscore "_" as a delimiter. +This naming scheme is usually the same as used for the source tarball name. + *Examples:* .... @@ -158,22 +263,41 @@ SDL_ttf (TrueType font rendering support for SDL, relies on SDL) === Eclipse plugins -Eclipse plugin packages MUST be named `+eclipse-+`. For example, a package of the AnyEdit plugin for Eclipse would be named `+eclipse-anyedit+`. +Eclipse plugin packages MUST be named `+eclipse-+`. +For example, +a package of the AnyEdit plugin for Eclipse would be named +`+eclipse-anyedit+`. === emacs components -Packages of emacs add-on components (code that adds additional functionality to emacs compatible editors) have their own naming -scheme. It is often the case that a component will add functionality to several different compatible editors, such as GNU -Emacs and XEmacs (and possibly development versions of these editors). The package name SHOULD take into account the upstream name of the -emacs component. - -Where a component adds functionality to more than one emacs compatible editor, the package name SHOULD be of the form emacs-common-$NAME. In this -case, the main package SHOULD contain only files common to all emacs compatible editors, and the code specific to each SHOULD be placed in a -subpackage reflecting the specific editor $EDITOR-$NAME eg. xemacs-$NAME, emacs-$NAME (the latter being the package specific to GNU Emacs). An -example of this scheme can be found in the package emacs-common-muse. - -Where a component is designed to add functionality to only a single emacs compatible editor, the main package name SHOULD reflect this by being -called $EDITOR-$NAME. An example of this situation can be found in the package emacs-auctex, which is built only for GNU Emacs. +Packages of emacs add-on components +(code that adds additional functionality to emacs compatible editors) +have their own naming scheme. +It is often the case that a component will add functionality +to several different compatible editors, +such as GNU Emacs and XEmacs +(and possibly development versions of these editors). +The package name SHOULD take into account the upstream name +of the emacs component. + +Where a component adds functionality to more than one emacs compatible editor, +the package name SHOULD be of the form emacs-common-$NAME. +In this case, +the main package SHOULD contain only files common +to all emacs compatible editors, +and the code specific to each SHOULD be placed +in a subpackage reflecting the specific editor $EDITOR-$NAME +eg. xemacs-$NAME, emacs-$NAME +(the latter being the package specific to GNU Emacs). +An example of this scheme can be found in the package +emacs-common-muse. + +Where a component is designed to add functionality +to only a single emacs compatible editor, +the main package name SHOULD reflect this +by being called $EDITOR-$NAME. +An example of this situation can be found in the package +emacs-auctex, which is built only for GNU Emacs. *Examples:* @@ -185,7 +309,13 @@ emacs-autex (autex component only for GNU Emacs) === erlang modules -Packages of erlang modules (thus they rely on erlang as a parent) have their own naming scheme. They SHOULD take into account the upstream name of the erlang module. This makes a package name format of `+erlang-$NAME+`. When in doubt, use the name of the module that you use when importing it into a script. +Packages of erlang modules +(thus they rely on erlang as a parent) +have their own naming scheme. +They SHOULD take into account the upstream name of the erlang module. +This makes a package name format of `+erlang-$NAME+`. +When in doubt, use the name of the module +that you use when importing it into a script. '''Example: ''' @@ -199,21 +329,43 @@ See the Packaging:GAP#Naming[GAP guidelines] for the proper naming of GAP addon === gnome shell extensions -Packages that extend gnome shell SHOULD begin with the prefix `+gnome-shell-extension-+`. In particular, this prefix SHOULD NOT be pluralized (ie: it SHOULD NOT be `+gnome-shell-extensions+`). +Packages that extend gnome shell SHOULD begin +with the prefix `+gnome-shell-extension-+`. +In particular, this prefix SHOULD NOT be pluralized +(ie: it SHOULD NOT be `+gnome-shell-extensions+`). === OCaml modules -OCaml modules, libraries and syntax extensions SHOULD be named ocaml-foo. Examples include: ocaml-extlib, ocaml-ssl. +OCaml modules, libraries and syntax extensions +SHOULD be named ocaml-foo. +Examples include: ocaml-extlib, ocaml-ssl. -This naming does not apply to applications written in OCaml, which can be given their normal name. Examples include: mldonkey, virt-top, cduce. +This naming does not apply to applications written in OCaml, +which can be given their normal name. +Examples include: mldonkey, virt-top, cduce. === LibreOffice extensions -Packages of LibreOffice extensions (thus they rely on LibreOffice as a parent) have their own naming scheme. They must take into account the upstream name of the LibreOffice extension. This makes a package name format of `+libreoffice-$NAME+`. +Packages of LibreOffice extensions +(thus they rely on LibreOffice as a parent) +have their own naming scheme. +They must take into account the upstream name +of the LibreOffice extension. +This makes a package name format of `+libreoffice-$NAME+`. === perl modules -Packages of perl modules (thus they rely on perl as a parent) use a slightly different naming scheme. They SHOULD be named perl-CPANDIST where CPANDIST is the name of the packaged CPAN module distribution (which is almost always also the unit of perl module packaging). In the rare cases when a CPAN module distribution needs to be split into smaller subpackages eg. due to dependencies, the extra subpackages SHOULD be named perl-CPANDIST-Something. + +Packages of perl modules +(thus they rely on perl as a parent) +use a slightly different naming scheme. +They SHOULD be named perl-CPANDIST +where CPANDIST is the name of the packaged CPAN module distribution +(which is almost always also the unit of perl module packaging). +In the rare cases when a CPAN module distribution needs to be split +into smaller subpackages +eg. due to dependencies, +the extra subpackages SHOULD be named perl-CPANDIST-Something. + '''Examples: ''' .... @@ -227,18 +379,21 @@ For details on the PHP naming scheme, see Packaging/PHP#NamingScheme . === Python modules -Python packaging is complicated by the fact that there are two partially incompatible -language versions in use, here called Python2 and Python3. However, the -common case is for one source package to produce a binary package for each -Python version, and this results in a naming convention where the source package -does not generally produce a binary package of the same name. +Python packaging is complicated by the fact +that there are two partially incompatible language versions in use, +here called Python2 and Python3. +However, the common case is for one source package to produce +a binary package for each Python version, +and this results in a naming convention where +the source package does not generally produce a binary package of the same name. -The package name SHOULD reflect the upstream name of the Python module, and -SHOULD generally take into account the name of the module used when importing -it in Python scripts. This name will be prefixed depending on the type of the package. +The package name SHOULD reflect the upstream name of the Python module, +and SHOULD generally take into account the name of the module +used when importing it in Python scripts. +This name will be prefixed depending on the type of the package. -Note that when a module that has a dot in its name, the link:#Separators[ usual rule] -about changing "." to "-" applies. +Note that when a module that has a dot in its name, the +link:#Separators[ usual rule] about changing "." to "-" applies. === Python source package naming @@ -251,10 +406,11 @@ python-psycopg (python module named psycopg) python-PyQt4 (python module named PyQt4) .... -However, it does occur that two separately maintained modules have the same -name but are targeted against different versions of Python. In this case, -source package for the software targeted at Python2 SHOULD take a -`+python2-+` prefix, and the source package for the Python3 version +However, it does occur that two separately maintained modules +have the same name but are targeted against different versions of Python. +In this case, source package for the software targeted at Python2 +SHOULD take a `+python2-+` prefix, +and the source package for the Python3 version SHOULD have a name beginning with `+python3-+`. ==== Python2 binary package naming @@ -267,7 +423,12 @@ Python3 binary packages MUST be named with a prefix of `+python3-+`. === R modules -Packages of R modules (thus they rely on R as a parent) have their own naming scheme. They SHOULD take into account the upstream name of the R module. This makes a package name format of `+R-$NAME+`. When in doubt, use the name of the module that you type to import it in R. +Packages of R modules +(thus they rely on R as a parent) +have their own naming scheme. +They SHOULD take into account the upstream name of the R module. +This makes a package name format of `+R-$NAME+`. +When in doubt, use the name of the module that you type to import it in R. '''Examples: ''' @@ -279,15 +440,20 @@ R-waveslim (R module named waveslim) === Sugar Activities -The name for all packaged Sugar activities must be prefixed with sugar-. For more details, see Packaging/SugarActivityGuidelines . +The name for all packaged Sugar activities must be prefixed with sugar-. +For more details, see Packaging/SugarActivityGuidelines . === Tcl/Tk extensions -The name for all packaged Tcl/Tk extensions must be prefixed with tcl-. This rule applies even for Tcl/Tk packages that are already prefixed with tcl in the name. For more details, see Packaging/Tcl#NamingConventions. +The name for all packaged Tcl/Tk extensions must be prefixed with tcl-. +This rule applies even for Tcl/Tk packages +that are already prefixed with tcl in the name. +For more details, see Packaging/Tcl#NamingConventions. === locales -If a package adds a locale to an existing parent package, then it can use an underscore in the locale. +If a package adds a locale to an existing parent package, +then it can use an underscore in the locale. '''Examples: ''' @@ -298,10 +464,15 @@ ttfonts-zh_CN (adds zh_CN locale fonts in ttfonts family) === TeX -As Fedora has switched TeX environments in the past, TeX packages SHOULD not -be named after the TeX environment (TeX Live or teTeX) but instead SHOULD -carry the prefix "tex-". +As Fedora has switched TeX environments in the past, +TeX packages SHOULD not be named after the TeX environment +(TeX Live or teTeX) +but instead SHOULD carry the prefix "tex-". == Authorship -The original author of these guidelines was link:TomCallaway[Tom 'spot' Callaway]. They are now maintained by the link:Packaging_Committee[Packaging Committee] with input from the Fedora community. +The original author of these guidelines was +link:TomCallaway[Tom 'spot' Callaway]. +They are now maintained by the +link:Packaging_Committee[Packaging Committee] +with input from the Fedora community.