From 3ce96e55b17867e61ffb30872f69b019660e149c Mon Sep 17 00:00:00 2001 From: Igor Gnatenko Date: Oct 04 2018 13:40:22 +0000 Subject: python: fix markup Signed-off-by: Igor Gnatenko --- diff --git a/guidelines/modules/ROOT/examples/python-example.spec b/guidelines/modules/ROOT/examples/python-example.spec new file mode 100644 index 0000000..9eee928 --- /dev/null +++ b/guidelines/modules/ROOT/examples/python-example.spec @@ -0,0 +1,43 @@ +%global srcname example + +Name: python-%{srcname} +Version: 1.2.3 +Release: 1%{?dist} +Summary: Example python module + +License: MIT +URL: https://pypi.python.org/pypi/example +Source0: %{pypi_source} + +BuildArch: noarch + +%description +An python module which provides a convenient example. + +%package -n python3-%{srcname} +Summary: %{summary} +BuildRequires: python3-devel +%{?python_provide:%python_provide python3-%{srcname}} + +%description -n python3-%{srcname} +An python module which provides a convenient example. + +%prep +%autosetup -n %{srcname}-%{version} + +%build +%py3_build + +%install +%py3_install + +%check +%{__python3} setup.py test + +# Note that there is no %%files section for the unversioned python module +%files -n python3-%{srcname} +%license COPYING +%doc README.rst +%{python3_sitelib}/%{srcname}-*.egg-info/ +%{python3_sitelib}/%{srcname}/ +%{_bindir}/sample-exec diff --git a/guidelines/modules/ROOT/nav.adoc b/guidelines/modules/ROOT/nav.adoc index 32fe1b4..0d40f3c 100644 --- a/guidelines/modules/ROOT/nav.adoc +++ b/guidelines/modules/ROOT/nav.adoc @@ -10,7 +10,7 @@ * xref:D.adoc[D] * xref:Debuginfo.adoc[Debuginfo] * xref:DefaultServices.adoc[DefaultServices] -* xref:Deprecating_Packages.adoc[Deprecating_Packages] +* xref:deprecating-packages.adoc[Deprecating Packages] * xref:DevAssistant.adoc[DevAssistant] * xref:Directory_Replacement.adoc[Directory_Replacement] * xref:DistTag.adoc[DistTag] diff --git a/guidelines/modules/ROOT/pages/Deprecating_Packages.adoc b/guidelines/modules/ROOT/pages/Deprecating_Packages.adoc deleted file mode 100644 index 001b14f..0000000 --- a/guidelines/modules/ROOT/pages/Deprecating_Packages.adoc +++ /dev/null @@ -1,47 +0,0 @@ -__TOC__ - -Sometimes a package is intended to be link:How_to_remove_a_package_at_end_of_life[removed from Fedora], but it is kept in Fedora for some additional (often indeterminate) time for various reasons including maintaining backwards compatibility. In order to prevent new packages from depending on such a package, it can be marked as *deprecated*. - -== Prerequisites for deprecation - -If nothing in Fedora depends on a package, a maintainer may deprecate it at their leisure. A maintainer (or collection of maintainers) may also deprecate a set of packages together if no package in that set is a dependency of any package outside of that set. - -If a package is a dependency of other packages in the distribution (which are not to be deprecated) then deprecation requires a link:Changes/Policy[FESCo approved Fedora change]. A packager SHOULD communicate package deprecation to other maintainers, preferably via the https://lists.fedoraproject.org/archives/list/devel@lists.fedoraproject.org/[devel] or https://lists.fedoraproject.org/archives/list/devel-announce@lists.fedoraproject.org/[devel-announce] mailing lists. - -== Marking a package deprecated - -In order to mark a package deprecated, a special virtual provides is added: - -`+ Provides: deprecated()+` - -If the package has subpackages and the packager intends to deprecate the package as a whole, packager MUST mark all subpackages as being deprecated. - -`+Name:      mainpackage+` + -`+...+` + -`+Provides:  deprecated()+` + - + -`+...+` + - + -`+%package subpackage+` + -`+...+` + -`+Provides:  deprecated()+` - -Alternatively, a packager MAY decide to only deprecate some subpackages. - -A packager SHOULD add a comment in the spec explaining why a package is being deprecated. For example: - -`+# net-tools (ifconfig etc.) have been obsoleted for ~20 years upstream.+` + -`+# We want to get rid of it from Fedora in favor of the iproute package,+` + -`+# however many sysadmins still expect ifconfig to be there, so we keep it+` + -`+# around as a deprecated package.+` + -`+Provides:  deprecated()+` - -If a date for the final removal of the package from the distribution is known, it MAY be included as follows: - -`+Provides:  deprecated() == YYYYMMDD+` - -The special `+deprecated()+` provide MUST NOT be added in any released branch of Fedora. It is acceptable to deprecate packages in rawhide (the master branch), the branch for an upcoming Fedora release (if one exists) up until the time of the link:Schedule[Final Freeze], and to EPEL branches (at any time). Also note that because packages may exist in a deprecated state for some time, those packages can eventually enter release branches. The restriction is on the initial addition of the `+deprecated()+` tag. - -== Consequences of a package being deprecated - -Technically, nothing changes; a deprecated package works and behaves as before. However, other packages in Fedora MUST NOT add a dependency on a deprecated package (that includes Requires, BuildRequires, Recommends, Suggests, etc.). This applies both for updates of existing packages and new packages added to Fedora. Those submitting new packages, along with package reviewers, MUST check to see if any dependencies of the package they are submitting or reviewing have been deprecated. (It is, however, acceptable for a deprecated package to be renamed.) diff --git a/guidelines/modules/ROOT/pages/Python.adoc b/guidelines/modules/ROOT/pages/Python.adoc index 22d36e2..5b9d894 100644 --- a/guidelines/modules/ROOT/pages/Python.adoc +++ b/guidelines/modules/ROOT/pages/Python.adoc @@ -1,24 +1,24 @@ = Python Packaging Guidelines -__TOC__ - == Python Version Support -In Fedora we have multiple Python runtimes, one for each supported major Python release. At this point that's one for python3.x and one for python2.7 However the python2 stack will be removed from Fedora and is Packaging:Deprecating_Packages[deprecated]. Upstream support for the python2 interpreter officially ends in 2020. If a piece of software supports python3, it MUST be packaged for python3. Software using python2 MUST NOT be newly packaged without FESCo exception. +In Fedora we have multiple Python runtimes, one for each supported major Python release. At this point that's one for python3.x and one for python2.7 However the python2 stack will be removed from Fedora and is xref:deprecating-packages.adoc[deprecated]. Upstream support for the python2 interpreter officially ends in 2020. If a piece of software supports python3, it MUST be packaged for python3. Software using python2 MUST NOT be newly packaged without FESCo exception. -For guidelines on maintaining already existing python2 packages, see the Packaging:Python_Appendix[appendix]. +For guidelines on maintaining already existing python2 packages, see the xref:Python_Appendix.adoc[appendix]. == Multiple Python Runtimes -For backwards compatibility, `+/usr/bin/python+` is, if it is installed, a symbolic link to `+/usr/bin/python2+`. +For backwards compatibility, `/usr/bin/python` is, if it is installed, a symbolic link to `/usr/bin/python2`. -Packages in Fedora MUST NOT use `+/usr/bin/python+`. Instead packages for Python 3 MUST use `+/usr/bin/python3+` (even if upstream supports both Python 2 and 3). As a result of that `+/usr/bin/python+` (as well as `+/usr/bin/env python+` and similar) MUST NOT be used in shebang lines or as a dependency of a package. As of Fedora 30, all uses of unversioned python executables in shebang lines will fail the build. +Packages in Fedora MUST NOT use `/usr/bin/python`. Instead packages for Python 3 MUST use `/usr/bin/python3` (even if upstream supports both Python 2 and 3). As a result of that `/usr/bin/python` (as well as `/usr/bin/env python` and similar) MUST NOT be used in shebang lines or as a dependency of a package. As of Fedora 30, all uses of unversioned python executables in shebang lines will fail the build. These shebangs MUST be fixed. If it is necessary to disable the checks, please see the information in Packaging:Guidelines#Shebang_lines. All python runtimes have a virtual provide for `+python(abi) = $MAJOR-$MINOR+`. For example, the Python 3.7 runtime package has: -`+ $ rpm -q --provides python3 |grep -i abi+` + -`+ python(abi) = 3.7+` +.... +$ rpm -q --provides python3 | grep abi +python(abi) = 3.7 +.... Python modules using these runtimes should have a corresponding "Requires" line on the python runtime that they are used with. This is done automatically for files below `+/usr/lib[^/]*/python${PYVER}+` @@ -26,62 +26,67 @@ Mirroring the policy for regular packages, the Python-version-specific subpackag == Naming -The source package for a Python library MUST be named with the `+python-+` prefix. A built package however must include the Python major version in the name, using the `+python3-+` prefix. This is accomplished by adding a subpackage. See example bellow. +The source package for a Python library MUST be named with the `python-` prefix. A built package however must include the Python major version in the name, using the `python3-` prefix. This is accomplished by adding a subpackage. See example bellow. This rule does not apply to applications. == Dependencies -Packages building for Python 3 will need `+BuildRequires: python3-devel+`. +Packages building for Python 3 will need `BuildRequires: python3-devel`. -Packages MUST NOT have dependencies (either build-time or runtime) on packages named with the unversioned `+python-+` prefix. Dependencies on Python packages instead MUST use names beginning with `+python3-+`. +Packages MUST NOT have dependencies (either build-time or runtime) on packages named with the unversioned `python-` prefix. Dependencies on Python packages instead MUST use names beginning with `python3-`. === Automatically generated dependencies -Packages MAY use the automatic Python dependency generator. This generator uses upstream egg/dist metadata (such as https://python-packaging.readthedocs.io/en/latest/dependencies.html[setuptool's install_requires]) to determine what the package should depend on. The generator parses the installed metadata from `+/usr/lib(64)?/pythonX.Y/site-packages/+``+-+``+-pyX.Y.(egg|dist)-info/requires.txt+`, so it will not work with software that uses plain https://docs.python.org/3/distutils/[distutils]. +Packages MAY use the automatic Python dependency generator. This generator uses upstream egg/dist metadata (such as https://python-packaging.readthedocs.io/en/latest/dependencies.html[setuptool's install_requires]) to determine what the package should depend on. The generator parses the installed metadata from `+/usr/lib(64)?/pythonX.Y/site-packages/[^/]+.(egg|dist)-info/requires.txt+`, so it will not work with software that uses plain https://docs.python.org/3/distutils/[distutils]. To enable this feature, add: `+%{?python_enable_dependency_generator}+` Although this statement can be used anywhere in the spec, we recommend putting it just before the main package's `+%description+` declaration. -This generates run time requires in the form of `+pythonX.Ydist(foo)+`. If the generated dependencies are not accurate, additional ones can still be added manually. To remove some, a packager MAY modify upstream-provided metadata (usually specified in the `+setup.py+` file) in the `+%prep+` section of the specfile or fall back to Packaging:AutoProvidesAndRequiresFiltering[filtering] those dependencies. +This generates run time requires in the form of `+pythonX.Ydist(foo)+`. If the generated dependencies are not accurate, additional ones can still be added manually. To remove some, a packager MAY modify upstream-provided metadata (usually specified in the `setup.py` file) in the `+%prep+` section of the specfile or fall back to xref:AutoProvidesAndRequiresFiltering.adoc[filtering] those dependencies. The packager MUST inspect the generated requires for correctness. All dependencies MUST be resolvable within the targeted Fedora version. As an example, the upstream notebook package has (as of version 5.6.0): -`+install_requires = [+` + -`+    'jinja2',+` + -`+    'tornado>=4',+` + -`+    'pyzmq>=17',+` + -`+    'ipython_genutils',+` + -`+    'traitlets>=4.2.1',+` + -`+    'jupyter_core>=4.4.0',+` + -`+    'jupyter_client>=5.2.0',+` + -`+    'nbformat',+` + -`+    'nbconvert',+` + -`+    'ipykernel',+` + -`+    'Send2Trash',+` + -`+    'terminado>=0.8.1',+` + -`+    'prometheus_client'+` + -`+],+` +[source,python] +---- +install_requires = [ +    'jinja2', +    'tornado>=4', +    'pyzmq>=17', +    'ipython_genutils', +    'traitlets>=4.2.1', +    'jupyter_core>=4.4.0', +    'jupyter_client>=5.2.0', +    'nbformat', +    'nbconvert', +    'ipykernel', +    'Send2Trash', +    'terminado>=0.8.1', +    'prometheus_client' +], +---- And the resulting dependencies: -`+python3.7dist(ipykernel)+` + -`+python3.7dist(ipython-genutils)+` + -`+python3.7dist(jinja2)+` + -`+python3.7dist(jupyter-client) >= 5.2.0+` + -`+python3.7dist(jupyter-core) >= 4.4.0+` + -`+python3.7dist(nbconvert)+` + -`+python3.7dist(nbformat)+` + -`+python3.7dist(prometheus-client)+` + -`+python3.7dist(pyzmq) >= 17+` + -`+python3.7dist(send2trash)+` + -`+python3.7dist(terminado) >= 0.8.1+` + -`+python3.7dist(tornado) >= 4+` + -`+python3.7dist(traitlets) >= 4.2.1+` +.... +python3.7dist(ipykernel) +python3.7dist(ipython-genutils) +python3.7dist(jinja2) +python3.7dist(jupyter-client) >= 5.2.0 +python3.7dist(jupyter-core) >= 4.4.0 +python3.7dist(nbconvert) +python3.7dist(nbformat) +python3.7dist(prometheus-client) +python3.7dist(pyzmq) >= 17 +python3.7dist(send2trash) +python3.7dist(terminado) >= 0.8.1 +python3.7dist(tornado) >= 4 +python3.7dist(traitlets) >= 4.2.1 +.... This generator will most likely be enabled by default in the future. If a packager wishes to explicitly opt out of the generator because the upstream metadata are not applicable, a packager MUST NOT assume that the generator won't be used simply because it is not enabled explicitly. Rather, they SHOULD opt out explicitly by adding: @@ -89,7 +94,7 @@ This generator will most likely be enabled by default in the future. If a packag == Provides -Using a fictional module named "example", the subpackage containing the python3 version *must* provide `+python3-example+`. This is of course always the case if the subpackage is named `+python3-example+` (as in the examples below). If the subpackage has some other name then then `+Provides: python3-example+` must be added explicitly (but see the `+%python_provide+` macro below). +Using a fictional module named "example", the subpackage containing the python3 version *must* provide `python3-example`. This is of course always the case if the subpackage is named `python3-example` (as in the examples below). If the subpackage has some other name then then `Provides: python3-example` must be added explicitly (but see the `+%python_provide+` macro below). === The %python_provide macro @@ -116,7 +121,7 @@ The `+3.Y+` is the Python version used (usually 3.6 and higher), and between the These Provides tags can be used to list Requires and BuildRequires of a package using the _standardized names_ (i.e. dist name, name on PyPI) of Python modules. To make it easier, you can use the `+%{py3_dist}+` macro that accept one or more parameters: the _standardized name(s)_ of the desired Python software. It will convert the name(s) to the _canonical format_ and create the proper `+python3dist(...)+` tag(s). -In addition, you can use the %\{py_dist_name} macro that simply transforms any _standardized name_ to the _canonical format_. +In addition, you can use the `+%{py_dist_name}+` macro that simply transforms any _standardized name_ to the _canonical format_. For example: @@ -137,7 +142,7 @@ When packaging software which is available from PyPI, you can make use of the `+ 1. The name of the PyPI project. Defaults to `+%srcname+` if defined, or to `+%pypi_name+` if defined, or to `+%name+` (the package name). 2. The version of the PyPI project. Defaults to `+%version+` (the package version). -3. The file extension to use. Defaults to `+tar.gz+`. +3. The file extension to use. Defaults to `tar.gz`. In most cases it is not necessary to specify any arguments. @@ -145,24 +150,65 @@ In most cases it is not necessary to specify any arguments. The following macros are defined for you in all supported Fedora and EPEL releases: -[cols=",,",options="header",] -|=========================================================================================================================================================================================================================================================================================================================================== -|Macro |Normal Definition |Notes -|__python |/usr/bin/python |Prohibited (see note below) -|__python3 |/usr/bin/python3 |Python 3 interpreter -|python_provide |(Lua script) |Given a package name, evaluates to either `+Provides: python-example+` or nothing at all depending on the Python version. See [[Packaging:Python#The_.25python_provide_macro |here]] for an example. -|python3_sitelib |/usr/lib/python3.X/site-packages |Where pure python3 modules are installed -|python3_sitearch |/usr/lib64/python3.X/site-packages on x86_64 + -/usr/lib/python3.X/site-packages on x86 |Where python3 extension modules that are compiled C are installed -|py3_dist |(Lua script) |Given a standardized name (i.e. dist name, name on PyPI) of Python software, it will convert it to a canonical format, and evaluates to `+python3dist(CANONICAL_NAME)+`, which is useful when listing dependencies. See [[Packaging:Python#Automatic_Provides_with_a_standardized_name |above]] for more information. -|py_byte_compile |(script) |Defined in python3-devel. See the [[Packaging:Python_Appendix#Manual_byte_compilation |byte compiling]] section for usage -|python3_version |3.X |Defined in python3-devel. Useful when running programs with Python version in filename, such as nosetest-%\{python3_version} -|python3_version_nodots |3X |Defined in python3-devel. Useful when listing files explicitly in %files section , such as %\{python3_sitelib}/foo/*.cpython-%\{python3_version_nodots}.pyo -|py3_build |%\{__python3} setup.py build ... |Various flags are added, see /usr/lib/rpm/macros.d/macros.python3 for details and similar macros. Define %py_setup_args to pass custom command line arguments to setup.py. -|py3_install |%\{__python3} setup.py install --skip-build ... | -|py_dist_name |(Lua script) |Given a standardized name (i.e. dist name, name on PyPI) of Python software, it will convert it to a canonical format. See [[Packaging:Python#Automatic_Provides_with_a_standardized_name |above]] for more information. -|pypi_source |(Lua script) |Evaluates to the appropriate URL for the package. See above for more information. -|=========================================================================================================================================================================================================================================================================================================================================== +[%header,cols=3*] +|=== +|Macro +|Expanded path +|Notes + +|`+%{__python}+` +|`+/usr/bin/python+` +|Prohibited (see note below). + +|`+%{__python3}+` +|`+/usr/bin/python3+` +|Python 3 interpreter. + +|`+%{python_provide}+` +|(Lua script) +|Given a package name, evaluates to either `Provides: python-$name` or nothing at all depending on the Pythonversion. See <> for an example. + +|`+%{python3_sitelib}+` +|`+/usr/lib/python3.X/site-packages+` +|Where pure python3 modules are installed. + +|`+%{python3_sitearch}+` +|`+/usr/lib64/python3.X/site-packages+` on 64bit architectures (e.g. x86_64) and `+/usr/lib/python3.X/site-packages+` on 32bit. +|Where python3 extension modules (e.g. C compiled) are installed. + +|`+%{py_byte_compile}+` +|(script) +|See xref:Python_Appendix.adoc#manual-bytecompilation[byte-compiling] section for usage. + +|`+%{python3_version}+` +|`+3.X+` +|Python 3 version. Useful when running programs with Python version in filename, such as `+nosetest-%{python3_version}+`. + +|`+%{python3_version_nodots}+` +|`+3X+` +|Python 3 version without dots. Useful when listing files explicitly in %files section, such as `+%{python3_sitelib}/foo/*.cpython-%{python3_version_nodots}.pyo+` + +|`+%py3_build+` +|`+%{__python3} setup.py build …+` +|Various flags are added, see `/usr/lib/rpm/macros.d/macros.python3` for details and similar macros. Define `+%py_setup_args+` to pass custom command line arguments to `setup.py`. + +|`+%py3_install+` +|`+%{__python3} setup.py install --skip-build …+` +| + +|`+%{py_dist_name}+` +|(Lua script) +|Given a standardized name (i.e. dist name, name on PyPI) of Python software, it will convert it to a canonical format. See <> for more information. + +|`+%{py3_dist}+` +|(Lua script) +|Given a standardized name (i.e. dist name, name on PyPI) of Python software, it will convert it to a canonical format, and evaluates to `+python3dist(CANONICAL_NAME)+`, which is useful when listing dependencies. See <> for more information. + +|`+%{pypi_source}+` +|(Lua script) +|Evaluates to the appropriate URL for the package. See above for more information. + +|=== During `+%install+` or when listing `+%files+` you can use the `+python3_sitearch+` and `+python3_sitelib+` macros to specify where the installed modules are to be found. For instance: @@ -206,9 +252,9 @@ Python will automatically try to byte compile files when it runs in order to spe The .pyc files contain byte code that is portable across OSes. If you do not include them in your packages, python will try (and generally fail) to create them when the user runs the program. If the system administrator runs the program, then the files will be successfully written, causing stray .pyc files which will not be removed when the package is removed. To prevent that the byte compiled files need to be compiled and included in the `+%files+` section. Normally, byte compilation is done for you by the `+brp-python-bytecompile+` script. This script runs after the `+%install+` section of the spec file has been processed and byte compiles any .py files that it finds in `+%{python3_sitelib}+` or `+%{python3_sitearch}+` (this recompilation puts the proper filesystem paths into the modules otherwise tracebacks would include the `+%{buildroot}+` in them). -You must include the .pyc files in your package. If the build process creates a __pycache__ directory in a subdirectory of %\{python3_sitearch} or %\{python3_sitelib}, you must also include all items in the __pycache__ directory. You MUST NOT include the directories %\{python3_sitearch}/__pycache__ or %\{python3_sitelib}/__pycache__ because they are already owned by the python3-libs package. +You must include the .pyc files in your package. If the build process creates a `+__pycache__+` directory in a subdirectory of `+%{python3_sitearch}+` or `+%{python3_sitelib}+`, you must also include all items in the `+__pycache__+` directory. You MUST NOT include the directories `+%{python3_sitearch}/__pycache__+` or `+%{python3_sitelib}/__pycache__+` because they are already owned by the python3-libs package. -All that you need to do is include the files in the `+%files+` section (replacing %\{python3_sitelib} with the appropriate macro for your package): +All that you need to do is include the files in the `+%files+` section (replacing `+%{python3_sitelib}+` with the appropriate macro for your package): .... %files @@ -225,71 +271,27 @@ or, if the python code installs directly into %\{python3_sitelib}: === Manual byte compilation -For more details on the internals of byte compilation, please see Packaging:Python_Appendix#Manual_byte_compilation[the appendix]. +For more details on the internals of byte compilation, please see xref:Python_Appendix.adoc#manual-bytecompilation[the appendix]. == Example Python spec file The following is a very simple spec file for a Python module. -.... -%global srcname example - -Name: python-%{srcname} -Version: 1.2.3 -Release: 1%{?dist} -Summary: An example python module - -License: MIT -URL: https://pypi.python.org/pypi/%{srcname} -Source0: %pypi_source - -BuildArch: noarch -BuildRequires: python3-devel - -%description -An python module which provides a convenient example. - - -%package -n python3-%{srcname} -Summary: %{summary} -%{?python_provide:%python_provide python3-%{srcname}} - -%description -n python3-%{srcname} -An python module which provides a convenient example. - - -%prep -%autosetup -n %{srcname}-%{version} - -%build -%py3_build - -%install -%py3_install - -%check -%{__python3} setup.py test - -# Note that there is no %%files section for the unversioned python module -%files -n python3-%{srcname} -%license COPYING -%doc README.rst -%{python3_sitelib}/%{srcname}/ -%{python3_sitelib}/%{srcname}-*.egg-info/ -%{_bindir}/sample-exec - -%changelog -.... +.python-example.spec +[source] +---- +include::{examplesdir}/python-example.spec[] +---- == Packaging eggs -Please see the Python eggs Packaging:Python_Eggs[guidelines] for information specific to Python eggs. +Please see the Python eggs xref:Python_Eggs.adoc[guidelines] for information specific to Python eggs. == Reviewer checklist The following briefly summarizes the guidelines for reviewers to go over: -* *Must*: Python modules must be built from source. They cannot simply drop an egg or whl from upstream into the proper directory. (See Packaging:Guidelines#No_inclusion_of_pre-built_binaries_or_libraries[ prebuilt binaries Guidelines] for details) +* *Must*: Python modules must be built from source. They cannot simply drop an egg or whl from upstream into the proper directory. (See xref:What_Can_Be_Packaged.adoc#prebuilt-binaries-or-libraries[prebuilt binaries Guidelines] for details). * *Must*: Python modules must not download any dependencies during the build process. * *Must*: When building a compat package, it must install using easy_install -m so it won't conflict with the main package. * *Must*: When building multiple versions (for a compat package) one of the packages must contain a default version that is usable via "import MODULE" with no prior setup. diff --git a/guidelines/modules/ROOT/pages/Python_Appendix.adoc b/guidelines/modules/ROOT/pages/Python_Appendix.adoc index cb0f67c..4ba1358 100644 --- a/guidelines/modules/ROOT/pages/Python_Appendix.adoc +++ b/guidelines/modules/ROOT/pages/Python_Appendix.adoc @@ -245,6 +245,7 @@ You should usually follow upstream's directions on how to run `+2to3+` and build * If you need to run `+2to3+` to fix code, use `+2to3+` or `+/usr/bin/2to3+`. At the moment, this program is coming from the `+python-tools+` rpm. Using `+2to3+` means that you'll be using a name that is supported upstream and across distros rather than `+/usr/bin/python3-2to3+` which we have renamed in Fedora to avoid filesystem conflicts. This also makes it easier for us to test and eventually change from using the python2 `+2to3+` to the python3 `+2to3+`. We just need to change the python3 package to provide the `+/usr/bin/2to3+` program instead of python and all of our python packages will start using that version instead. * If `+2to3+` runs into a problem, please https://bugzilla.redhat.com/enter_bug.cgi?component=python&product=Fedora[file a Fedora bug]. Please try to isolate a minimal test case that reproduces the problem when doing so. +[#manual-bytecompilation] == Manual byte compilation When byte compiling a .py file, python embeds a magic number in the byte compiled files that correspond to the runtime. Files in `+%{python?_sitelib}+` and `+%{python?_sitearch}+` MUST correspond to the runtime for which they were built. For instance, a pure python module compiled for the 3.4 runtime MUST be below `+%{_usr}/lib/python3.4/site-packages+` diff --git a/guidelines/modules/ROOT/pages/What_Can_Be_Packaged.adoc b/guidelines/modules/ROOT/pages/What_Can_Be_Packaged.adoc index 9d9540d..57a4218 100644 --- a/guidelines/modules/ROOT/pages/What_Can_Be_Packaged.adoc +++ b/guidelines/modules/ROOT/pages/What_Can_Be_Packaged.adoc @@ -60,6 +60,7 @@ Fedora allows only a single kernel package; packages containing alternate kernel Fedora does not allow kernel modules to be packaged outside of the main kernel package. You should communicate with the link:Kernel[kernel team] regarding enabling additional kernel modules. +[#prebuilt-binaries-or-libraries] == No inclusion of pre-built binaries or libraries All program binaries and program libraries included in Fedora packages must be built from the source code that is included in the source package. This is a requirement for the following reasons: diff --git a/guidelines/modules/ROOT/pages/deprecating-packages.adoc b/guidelines/modules/ROOT/pages/deprecating-packages.adoc new file mode 100644 index 0000000..001b14f --- /dev/null +++ b/guidelines/modules/ROOT/pages/deprecating-packages.adoc @@ -0,0 +1,47 @@ +__TOC__ + +Sometimes a package is intended to be link:How_to_remove_a_package_at_end_of_life[removed from Fedora], but it is kept in Fedora for some additional (often indeterminate) time for various reasons including maintaining backwards compatibility. In order to prevent new packages from depending on such a package, it can be marked as *deprecated*. + +== Prerequisites for deprecation + +If nothing in Fedora depends on a package, a maintainer may deprecate it at their leisure. A maintainer (or collection of maintainers) may also deprecate a set of packages together if no package in that set is a dependency of any package outside of that set. + +If a package is a dependency of other packages in the distribution (which are not to be deprecated) then deprecation requires a link:Changes/Policy[FESCo approved Fedora change]. A packager SHOULD communicate package deprecation to other maintainers, preferably via the https://lists.fedoraproject.org/archives/list/devel@lists.fedoraproject.org/[devel] or https://lists.fedoraproject.org/archives/list/devel-announce@lists.fedoraproject.org/[devel-announce] mailing lists. + +== Marking a package deprecated + +In order to mark a package deprecated, a special virtual provides is added: + +`+ Provides: deprecated()+` + +If the package has subpackages and the packager intends to deprecate the package as a whole, packager MUST mark all subpackages as being deprecated. + +`+Name:      mainpackage+` + +`+...+` + +`+Provides:  deprecated()+` + + + +`+...+` + + + +`+%package subpackage+` + +`+...+` + +`+Provides:  deprecated()+` + +Alternatively, a packager MAY decide to only deprecate some subpackages. + +A packager SHOULD add a comment in the spec explaining why a package is being deprecated. For example: + +`+# net-tools (ifconfig etc.) have been obsoleted for ~20 years upstream.+` + +`+# We want to get rid of it from Fedora in favor of the iproute package,+` + +`+# however many sysadmins still expect ifconfig to be there, so we keep it+` + +`+# around as a deprecated package.+` + +`+Provides:  deprecated()+` + +If a date for the final removal of the package from the distribution is known, it MAY be included as follows: + +`+Provides:  deprecated() == YYYYMMDD+` + +The special `+deprecated()+` provide MUST NOT be added in any released branch of Fedora. It is acceptable to deprecate packages in rawhide (the master branch), the branch for an upcoming Fedora release (if one exists) up until the time of the link:Schedule[Final Freeze], and to EPEL branches (at any time). Also note that because packages may exist in a deprecated state for some time, those packages can eventually enter release branches. The restriction is on the initial addition of the `+deprecated()+` tag. + +== Consequences of a package being deprecated + +Technically, nothing changes; a deprecated package works and behaves as before. However, other packages in Fedora MUST NOT add a dependency on a deprecated package (that includes Requires, BuildRequires, Recommends, Suggests, etc.). This applies both for updates of existing packages and new packages added to Fedora. Those submitting new packages, along with package reviewers, MUST check to see if any dependencies of the package they are submitting or reviewing have been deprecated. (It is, however, acceptable for a deprecated package to be renamed.) diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index 7be1b6b..7317cbd 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -1472,7 +1472,7 @@ For packages that are not usually pulled in by using the package name as the dep == Deprecating Packages -A procedure exists for indicating that a package is deprecated and may leave the distribution in the future. See xref:Deprecating_Packages.adoc[Deprecating Packages]. +A procedure exists for indicating that a package is deprecated and may leave the distribution in the future. See xref:deprecating-packages.adoc[Deprecating Packages]. == Networking Support