EPEL/GuidelinesAndPolicies

From FedoraProject

< EPEL(Difference between revisions)
Jump to: navigation, search
(unnecessary python byte compiling on EL-5)
(Move all distribution specific packaging guidelines to the EPEL:Packaging page)
(16 intermediate revisions by 9 users not shown)
Line 1: Line 1:
 +
{{autolang|base=yes}}
 +
 
= Packaging Guidelines and Policies for EPEL =
 
= Packaging Guidelines and Policies for EPEL =
  
Line 80: Line 82:
 
issues or where the maintainer doesn't feel they are stable will be
 
issues or where the maintainer doesn't feel they are stable will be
 
held back from the stable push. Note that maintainers will need to request
 
held back from the stable push. Note that maintainers will need to request
their packages go to stable after 2 weeks or have sufficent karma in their update
+
their packages go to stable after 2 weeks or have sufficient karma in their update
 
to do so. No automatic promotions from testing to stable happen any longer.  
 
to do so. No automatic promotions from testing to stable happen any longer.  
  
Line 92: Line 94:
 
* The update MUST spend at least 2 weeks in testing, unless it's a security or critical bug fix.  
 
* The update MUST spend at least 2 weeks in testing, unless it's a security or critical bug fix.  
 
* After 2 weeks, bodhi will mail the maintainer to let them know it's been 2 weeks.  
 
* After 2 weeks, bodhi will mail the maintainer to let them know it's been 2 weeks.  
* If the Maintainer requests stable at this point or the update has sufficent karma it will be pushed to stable in the next push.  
+
* If the Maintainer requests stable at this point or the update has sufficient karma it will be pushed to stable in the next push.  
* Testing pushes take place nearly daily. Stable pushes happen bi-weekly on tuesdays.  
+
* Testing pushes take place nearly daily. Stable pushes happen bi-weekly on Tuesdays.  
* Updates never leave testing for stable unless the maintainer requests it, or there is sufficent karma. (NO autopromotion of updates).  
+
* Updates never leave testing for stable unless the maintainer requests it, or there is sufficient karma. (NO auto promotion of updates).
  
 
=== Guidelines and Backgrounds for this policy ===
 
=== Guidelines and Backgrounds for this policy ===
Line 116: Line 118:
 
the existing config files continue to work
 
the existing config files continue to work
  
* build as normal, but leave in testing until there is sufficent karma to go to stable.  
+
* build as normal, but leave in testing until there is sufficient karma to go to stable.
  
 
===== A yet again little bit bigger minor version updates =====
 
===== A yet again little bit bigger minor version updates =====
Line 178: Line 180:
 
released; many packages that get build for RHEL5 can't be build for
 
released; many packages that get build for RHEL5 can't be build for
 
RHEL4 at this point of time already, as the RHEL4-gtk2-Package is two
 
RHEL4 at this point of time already, as the RHEL4-gtk2-Package is two
years old and is to old for many current applications, as they depend
+
years old and is too old for many current applications, as they depend
 
on a newer gtk2. So if even if we would try to have a rolling scheme
 
on a newer gtk2. So if even if we would try to have a rolling scheme
with with quite new package we'd fail, as we can't build a bunch of
+
with quite new package we'd fail, as we can't build a bunch of
 
package due to this dependencies on libs; in the end we would have a
 
package due to this dependencies on libs; in the end we would have a
 
repo with some quite new packages while others are still quite
 
repo with some quite new packages while others are still quite
Line 189: Line 191:
  
 
{{Anchor|nomaintainerresponse}}
 
{{Anchor|nomaintainerresponse}}
 +
 
=== Getting a Fedora package in EPEL ===
 
=== Getting a Fedora package in EPEL ===
  
Line 194: Line 197:
  
 
=== Distribution specific guidelines ===
 
=== Distribution specific guidelines ===
 +
The [[Packaging:Guidelines| Fedora Packaging Guidelines]] are written for current Fedora releases.  Sometimes there are changes in Fedora that cause the packaging guidelines there to not make sense for the older software being run in RHEL.  When that occurs, we document the differences with the Fedora Packaging Guidelines on the [[EPEL:Packaging]] page.
  
==== EL4 ====
 
<ul>
 
<li>EPEL4 Python packages should manually depend on the proper python version that it was build for. Most old FC-3 python packages should still use this trick.</li>
 
<li>EPEL4 Python packages need to generate .pyc and .pyo files in the spec file.  If your module is using distutils or setuptools, use the following commands during %install:
 
<pre>
 
%{__python} setup.py install --skip-build --root $RPM_BUILD_ROOT
 
%{__python} setup.py install -O1 --skip-build --root $RPM_BUILD_ROOT
 
</pre></li>
 
</ul>
 
 
==== EL5 ====
 
<ul>
 
<li>rpm in EPEL5 and below does not automatically create dependencies for pkgconfig files.  Packages containing pkgconfig(.pc) files must <code>Requires: pkgconfig</code> (for directory ownership and usability).</li>
 
<li>in EPEL5 the automatic byte compilation of python files that is performed by brp-python-bytecompile byte compiles all files that match *.py  This is undesirable for program files in %{_bindir} and %{_sbindir} because the user will probably never invoke these files, only the main program file and python won't use these files.  Until the bug is resolved, there are two workarounds:
 
<ol>
 
<li>Rename scripts in %{_bindir} to not have a .py extension:  For instance, from /usr/bin/orient.py to /usr/bin/orient.</li>
 
<li>Use %exclude to exclude the scripts from the file listing:
 
<pre>
 
%files
 
%{_bindir}/orient.py
 
%exclude %{_bindir}/orient.pyc
 
%exclude %{_bindir}/orient.pyo
 
</pre></li>
 
</ol>
 
</li>
 
</ul>
 
 
[[Category:EPEL]]
 
[[Category:EPEL]]
  
Line 227: Line 205:
 
* EPEL packages must never conflict with packages in RHEL Base (Including Advanced Platform).
 
* EPEL packages must never conflict with packages in RHEL Base (Including Advanced Platform).
 
* EPEL packages can conflict with packages in other RHEL channels.
 
* EPEL packages can conflict with packages in other RHEL channels.
* EPEL maintainers should be open to communication from RHEL maintainers and try and accommodate them by not shipping specific packages, or by adjusting the package in  
+
* EPEL maintainers should be open to communication from RHEL maintainers and try and accommodate them by not shipping specific packages, or by adjusting the package in EPEL to better handle a conflicting package in a channel on a case by case basis.
* EPEL to better handle a conflicting package in a channel on a case by case basis.
+
 
 +
When a package is added to RHEL that is already in EPEL, we need to block it from being updated in EPEL.  Follow these steps to do that:
 +
 
 +
* 'dead.package' it in the cvs branch for the EL version where the package has been added
 +
* retire in pkgdb for the same branch
 +
* file a ticket with [https://fedorahosted.org/rel-eng rel-eng] to block it.
 +
 
 +
=== Conflicts in compat packages ===
 +
 
 +
Due to the EPEL policy of maintaining backwards compatibility, EPEL has a greater need for forward compat packages than Fedora.  When creating, a compat package, note that it is okay to set a Conflicts between them as noted in the [[Packaging:Conflicts#Compat_Package_Conflicts |Conflicts Guidelines]].  At this time, this is only allowed for packages overriding packages in EPEL, not in RHEL Base.

Revision as of 17:35, 27 March 2013

Contents

Packaging Guidelines and Policies for EPEL

The packages in EPEL follow the Fedora Packaging and Maintenance Guidelines -- that includes, but is not limited to the packaging guidelines , the package naming guidelines , the package review guidelines and the packaging policies that are designed and maintained by the FESCo and Packaging Committee . There are however some EPEL-specific exceptions, which you can find below.

Please note that the sections "Guidelines" and "Policies" use their names on purpose. Consider the guidelines as something that should be followed normally, but doesn't have to if there are good reasons not to -- please ask the EPEL SIG members in case you are in doubt if your reasons are good. The word policies has a stronger meaning, and what is written in that section should be considered rules that must always be followed.

Package maintenance and update policy

EPEL wants to provide a common "look and feel" to the users of our repository. Thus the EPEL SIG wrote this policy that describes the regulations for package maintenance and updates in EPEL, that are a bit more strictly regulated then they are in Fedora now.

Digest

The goal is to have packages in EPEL that enhances the Enterprise Linux distributions the packages were build against without disturbing or replacing packages from that distribution. The packages in the repository should, if possible, be maintained in similar ways to the Enterprise Packages they were built against. In other words: have a mostly stable set of packages that normally to not change at all and only changes if there are good reasons for it -- so no "hey, there is a new version, it builds, let's ship it" mentality.


Policy

EPEL packages should only enhance and never disturb the Enterprise Linux distributions they were build for. Thus packages from EPEL should never replace packages from the target base distribution - including those on the base distribution as well as layered products; kernel-modules further are not allowed, as they can disturb the base kernel easily.

The packages in the repository should, if possible, be maintained in similar ways to the Enterprise Packages they were built against. In other words: have a mostly stable set of packages that normally does not change at all and only changes if there are good reasons for changes. This is the spirit of a stable enterprise environment.

The changes that cant be avoided get routed into different release trees. Only updates that fix important bugs (say: data-corruption, security problems, really annoying bugs) go to a testing branch for a short time period and then are pushed to the stable branch; those people that sign and push the EPEL packages to the public repo will skim over the list of updated packages for the stable repo to make sure that sure the goal "only important updates for the stable branch" is fulfilled.

Other updates get queued up in a testing repository over time. That repository becomes the new stable branch after at LEAST 2 weeks of testing. But even these updates should be limited to fixes only as far as possible and should be tested in Fedora beforehand if possible. Updated Packages that change the ABI or require config file adjustments must be avoided if at all possible. Compat- Packages that provide the old ABI need to be provided in the repo if there is no way around a package update that changes the ABI. Packages in the testing repo that contain dependency issues or where the maintainer doesn't feel they are stable will be held back from the stable push. Note that maintainers will need to request their packages go to stable after 2 weeks or have sufficient karma in their update to do so. No automatic promotions from testing to stable happen any longer.

When a new quarterly update is released, EPEL will wait until the CentOS version of that update is available.

Workflow examples / Information

  • Maintainer builds the package normally using 'make build'
  • The Maintainer submits an update request using bodhi ('make update' or via the web interface).
  • The update MUST spend at least 2 weeks in testing, unless it's a security or critical bug fix.
  • After 2 weeks, bodhi will mail the maintainer to let them know it's been 2 weeks.
  • If the Maintainer requests stable at this point or the update has sufficient karma it will be pushed to stable in the next push.
  • Testing pushes take place nearly daily. Stable pushes happen bi-weekly on Tuesdays.
  • Updates never leave testing for stable unless the maintainer requests it, or there is sufficient karma. (NO auto promotion of updates).

Guidelines and Backgrounds for this policy

Some examples of what package updates that are fine or not

Examples hopefully help to outline how to actually apply above policy in practise.

Minor version updates

Let's assume package foo is shipped in EPEL 5.0 as version 1.0.1; upstream developers now ship 1.0.2

  • build as normal, but wait at least two weeks and possibly more in testing.
A little bit bigger minor version updates

Let's assume package foo is shipped in EPEL 5.0 as version 1.0.1; upstream developers now ship 1.2.0; the ABI is compatible to 1.0.1 and the existing config files continue to work

  • build as normal, but leave in testing until there is sufficient karma to go to stable.
A yet again little bit bigger minor version updates

Let's assume package foo is shipped in EPEL 5.0 as version 1.0.1; upstream developers now ship 1.4.0; the ABI is compatible to 1.0.1, but the config files need manual adjustments

  • build for the stable branch is normally not acceptable; a backport should be strongly considered if there are any serious bugs that must be fixed
  • build for the testing branch is also disliked; but it is acceptable if there is no other easy way out to solve serious bugs; but the update and the config file adjustments need to be announced to the users properly -- use the epel-announce list for this.
  • leave in testing if at all possible.
A major version update

Let's assume package foo is shipped in EPEL 5.0 as version 1.0.1; upstream developers now ship 2.0.0; the ABI changes or the config files need manual adjustments

  • this update should be avoided if possible at all. If there really is no other way out to fix a serious bug then it rare cases it might be acceptable to build the new version for the testing branch and mention the update and the needed adjustments in the release notes for the next update. An additional compat- packages with the old libs is necessary if the ABI changed.
Security Updates

Security updates should be marked as such in bodhi and will be pushed to stable. Because of this you should always try and make as few changes as possible on these sorts of updates. Apply only the backported fix, or if you must, the new version that provides only the fix. Try and avoid pushing other changes with a security update.

Add more examples as they show up

If to many show up put them into a separate document.

Still unsure if a package is fine for EPEL?

Just ask on EPEL developers mailing list or #epel on freenode.org for opinions from EPEL SIG members.

Why not a rolling release with latest packages like what was in Fedora Extras?

Why should we? That would be what Fedora Extras did and worked and works well for it -- but that's mainly because Fedora (Core) has lots of updates and a nearly rolling-release scheme/quick release cycle, too. But the Enterprise Linux we build against is much more careful with updates and has longer life-cycle; thus we should do the same for EPEL, as most users will properly prefer it that way, as they chose a stable distro for some reasons -- if they want the latest packages they might have chosen Fedora.

Sure, there are lots of areas where having a mix of a stable base and a set of quite new packages on top of it is wanted. *Maybe* the EPEL project will provide a solution (in parallel to the carefully updated repository!) for those cases in the long term, but not for the start. There are already third party repositories out there that provide something in this direction, so users might be served by them already.

Further: A rolling release scheme like Fedora Extras did is not possible for many EPEL packages for another reason, new packages often require new versions of certain core libraries. This will cause problems in EPEL because we won't be able to provide updated libs as it would replace libraries in the core OS.

Example: This document was written round about when RHEL5 got released; many packages that get build for RHEL5 can't be build for RHEL4 at this point of time already, as the RHEL4-gtk2-Package is two years old and is too old for many current applications, as they depend on a newer gtk2. So if even if we would try to have a rolling scheme with quite new package we'd fail, as we can't build a bunch of package due to this dependencies on libs; in the end we would have a repo with some quite new packages while others are still quite old. That mix wouldn't make either of the "latest versions" or "careful updates only" sides happy; so we try to target the "careful updates only" sides. Remember, EPEL's support and updates cycle is much longer then Fedora's.

Getting a Fedora package in EPEL

Look here for the procedure used to get a Fedora package in EPEL.

Distribution specific guidelines

The Fedora Packaging Guidelines are written for current Fedora releases. Sometimes there are changes in Fedora that cause the packaging guidelines there to not make sense for the older software being run in RHEL. When that occurs, we document the differences with the Fedora Packaging Guidelines on the EPEL:Packaging page.

Policy for Conflicting Packages

  • EPEL packages must never conflict with packages in RHEL Base (Including Advanced Platform).
  • EPEL packages can conflict with packages in other RHEL channels.
  • EPEL maintainers should be open to communication from RHEL maintainers and try and accommodate them by not shipping specific packages, or by adjusting the package in EPEL to better handle a conflicting package in a channel on a case by case basis.

When a package is added to RHEL that is already in EPEL, we need to block it from being updated in EPEL. Follow these steps to do that:

  • 'dead.package' it in the cvs branch for the EL version where the package has been added
  • retire in pkgdb for the same branch
  • file a ticket with rel-eng to block it.

Conflicts in compat packages

Due to the EPEL policy of maintaining backwards compatibility, EPEL has a greater need for forward compat packages than Fedora. When creating, a compat package, note that it is okay to set a Conflicts between them as noted in the Conflicts Guidelines. At this time, this is only allowed for packages overriding packages in EPEL, not in RHEL Base.