From 6293bbd9011e95fe97d89be88507663dd4835780 Mon Sep 17 00:00:00 2001 From: Troy Dawson Date: Mar 16 2022 14:06:13 +0000 Subject: first pass at examples, updates from comments --- diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc index 006b114..8e7aa0f 100644 --- a/modules/ROOT/nav.adoc +++ b/modules/ROOT/nav.adoc @@ -10,6 +10,7 @@ * xref:epel-help.adoc[Helping EPEL] ** xref:epel-qa.adoc[EPEL QA] ** xref:epel-packaging.adoc[Packaging] +** xref:epel-packaging-examples.adoc[Packaging Examples] ** xref:epel-package-maintainers.adoc[Package Maintainers] ** xref:epel-package-maintainer-generic-description.adoc[EPEL Package Maintainer Generic Description] ** xref:epel-rhel-entitlements.adoc[RHEL Entitlements] diff --git a/modules/ROOT/pages/epel-packaging-examples.adoc b/modules/ROOT/pages/epel-packaging-examples.adoc new file mode 100644 index 0000000..3fa31ca --- /dev/null +++ b/modules/ROOT/pages/epel-packaging-examples.adoc @@ -0,0 +1,147 @@ +include::partial$attributes.adoc[] += EPEL Packaging Examples +:toc: + +This page contains guidelines which are no longer relevant to Fedora, +but still apply to EPEL packages. These guidelines are designed to avoid +conflict with the larger Fedora Packaging Guidelines, but should any +conflicts occur, these guidelines should take precedence (on EPEL +packages). + +As a reminder, these guidelines only apply to EPEL packages, not to +Fedora packages. + +[[short_term]] +== Short Term + +=== Short Term Workflow + +This is an example workflow. + +* fedpkg request-repo --exception -epel +** fedpkg request-repo --exception pycairo-epel +* fedpkg request-branch --repo -epel epel +** fedpkg request-branch --repo pycairo-epel epel9 +** Note: request-repo and request-branch can be done at the same time as long as request-repo is done first +* Wait until you get an email saying the request is done +* fedpkg clone -epel ; cd -epel +** fedpkg clone pycairo-epel ; cd pycairo-epel +* fedpkg retire "For epel only, not Fedora" +* fedpkg switch-branch epel +** fedpkg switch-branch epel9 +* Download the source rpm corresponding to the lastest released RHEL build +* fedpkg import +** fedpkg import /tmp/pycairo-1.20.0-4.el9.src.rpm +* fedpkg commit -m "import from centos srpm" +* git mv .spec -epel.spec +** git mv pycairo.spec pycairo-epel.spec +* fedpkg commit -m "rename spec file" +* Edit the spec file so it builds, but only produces the missing binaries +* Test build and test install your rpm, which ever way you like to do that +* fedpkg commit -m "Convert RHEL to -epel with just -devel subpackage" +** fedpkg commit -m "Convert RHEL9 pycairo to pycairo-epel with just python3-cairo-devel subpackage" +* fedpkg push +* fedpkg build +* fedpkg update + +=== Short Term Spec Examples + +==== Header / Top of Spec + +.... +# This spec file is derived from the RHEL9 pycairo spec file. They should be kept +# in sync over time. +# https://gitlab.com/redhat/centos-stream/rpms/pycairo +%global rhel_name pycairo +%global _debugsource_template %{nil} +.... + +* State where the original spec came from, and where to look to make sure it is in sync. +* A variable for the original name of the package. It doesn't have to be rhel_name, but keep it consistent. +** Do a global replacement of %\{name} to %\{rhel_name} in your spec file. +* Turn off debugsource + +==== Prep +.... +%prep +%autosetup -p1 -n %{rhel_name}-%{version} +.... + +Add "-n %\{rhel_name}-%\{version}" to your setup. So the build doesn't think the source is in -epel-version. + +==== package description and files + +You need to add "-n %\{rhel_name}-" to each these. + +.... +%package -n %{rhel_name}-devel +%description -n %{rhel_name}-devel +%files -n %{rhel_name}-devel +.... + +==== Fix Requires: + +Most -devel packages have a Requires equal to the Name-Version-Release (NVR) +.... +%package -n %{rhel_name}-devel +Requires: %{rhel_name}%{?_isa} = %{version}-%{release} +.... + +If this were a perfect world, you could leave your -epel package like that. But it's not a perfect world, and there are many times you need to update your -epel package seperate from the RHEL package being updated. + +The following are two options. It is up to the -epel package maintainer to decide which is right for them, or perhaps do things your own way. + + Remove release + +If your -epel package only has some unchanging headers, you usually do not need to keep completely in step with the RHEL release, only the version. If that is the case, simply remove the -%\{release} section +.... +%package -n %{rhel_name}-devel +Requires: %{rhel_name}%{?_isa} = %{version} +.... + +If your -epel package has to be updated each time the RHEL package is updated, no matter what, one way to do this is with a %\{rhel_release} that goes along with your %\{rhel_name}. If you do this, your -epel release must be less than the RHEL release. +.... +... +%global rhel_name pycairo +%global rhel_release 4 +%global epel_release 1 +... +Name: %{rhel_name}-epel +Release: 0.%{rhel_release}%{?dist}.%{epel_release} +... +%package -n %{rhel_name}-devel +Requires: %{rhel_name}%{?_isa} = %{version}-%{rhel_release} +... +.... + +==== Remove files shipped in RHEL + +At the end of the %install section, remove all the files you will not be shipping. + +.... +%install +%py3_install + +# remove files shipped in RHEL +rm -rf %{buildroot}%{python3_sitearch} +.... + +==== Remove un-needed sections + +Need to remove + +* %files +** Remove all the %files sections you will not be shipping +** Make sure any file listed in those sections is removed in the %install section + +Optional remove +* %package and %description +* %prep %post and other scripts +* %check +** This really depends on what you are doing. If %check takes an hour, and all you need is a few headers, feel free remove it. If the missing package has an actual program in it, leave it in. +** When in doubt, leave %check in. + + +=== Un-Built Examples + +Put Examples and Tips Here diff --git a/modules/ROOT/pages/epel-policy-missing-sub-packages.adoc b/modules/ROOT/pages/epel-policy-missing-sub-packages.adoc index 969bde2..af7baa9 100644 --- a/modules/ROOT/pages/epel-policy-missing-sub-packages.adoc +++ b/modules/ROOT/pages/epel-policy-missing-sub-packages.adoc @@ -36,42 +36,20 @@ Short Term: Create an epel package that only has the missing packages, or missin * If you need help building this, ask for help. We have some examples. (examples coming soon) * It qualifies for an exception to the package review process so you can request the repo with ** fedpkg request-repo --exception -epel -* Once the repo is created, you should retire the rawhide branch to make it clear that this is an EPEL-only package and shouldn't be branched for future Fedora releases +* Once the repo is created, you must retire the rawhide branch to make it clear that this is an EPEL-only package and shouldn't be branched for future Fedora releases ** fedpkg retire 'EPEL-only package' * When/If the missing package(s) are added to RHEL CRB, retire your -epel package. [[long_term]] === Long Term -Long Term: Request the package be added to RHEL 8 and 9 CRB repository. +Long Term: Request the package be added to the appropriate RHEL CRB repository. -* To initiate this process, please file a bug in https://bugzilla.redhat.com and request it be added to RHEL 8 and 9. Report the bug against the "CentOS Stream" version of the "Red Hat Enterprise Linux 8" and/or "Red Hat Enterprise Linux 9" product. +* To initiate this process, please file a bug in https://bugzilla.redhat.com and request +it be added to RHEL. Report the bug against the "CentOS Stream" version of the +"Red Hat Enterprise Linux X" product, with "X" being the major version. * Be sure to say that it is impacting an EPEL build, and which package it is impacting. -In the past, the default answer for a request like this was "no". But in mid-2021 the RHEL policy changed to -allow the RHEL package maintainer to make the decision. There are still packages where the answer might -be "no", but many maintainers are choosing to add the sub-packages to the RHEL CRB repo. - -[[missing_un-built_sub-packages]] -== Missing Un-Built Sub-Packages - -You can create packages that supply missing sub-packages that were not built in RHEL but are built in Fedora. - -In the past these were named -extra, but these are now named (package>-epel to avoid confusion. - -[[examples]] -== Examples - -These examples are recommendations. If you want or need to do something different, you can. - -[[short_term_examples]] -=== Short Term Examples - -Put Examples and Tips Here - -[[long_term_examples]] -=== Long Term Examples - .... Please add to CRB in RHEL9 @@ -86,7 +64,15 @@ I am building in EPEL9. is important because uses it for .... -[[un-built_examples]] -=== Un-Built Examples +In the past, the default answer for a request like this was "no". +But in mid-2021 the RHEL policy changed to allow the RHEL package +maintainer to make the decision. There are still packages where +the answer might be "no", but many maintainers are choosing to add +the sub-packages to the RHEL CRB repo. -Put Examples and Tips Here +[[missing_un-built_sub-packages]] +== Missing Un-Built Sub-Packages + +You can create packages that supply missing sub-packages that were not built in RHEL but are built in Fedora. + +In the past these were named -extra, but these are now named (package>-epel to avoid confusion.