From 9ef3b5b9586dec2afa8c8ead5686c4171a9b8120 Mon Sep 17 00:00:00 2001 From: Otto Urpelainen Date: Feb 11 2022 21:28:03 +0000 Subject: [PATCH 1/3] Deduplicate tool installation instructions Many pages contained instructions for installing packager tooling. For most parts, the instructions were the same, but each page did something a bit differently than others. All of these separate instructions are merged to a single page here. Each page just links to that one page. --- diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc index 6ecffd2..6a0f5a2 100644 --- a/modules/ROOT/nav.adoc +++ b/modules/ROOT/nav.adoc @@ -1,4 +1,5 @@ * xref:Joining_the_Package_Maintainers.adoc[Joining the Package Maintainers] +** xref:Installing_Packager_Tools.adoc[Installing Packager Tools] ** xref:How_to_Get_Sponsored_into_the_Packager_Group.adoc[How to Get Sponsored into the Packager Group] * xref:How_to_Sponsor_a_New_Contributor.adoc[How to Sponsor a New Contributor] diff --git a/modules/ROOT/pages/Installing_Packager_Tools.adoc b/modules/ROOT/pages/Installing_Packager_Tools.adoc new file mode 100644 index 0000000..d13bdd0 --- /dev/null +++ b/modules/ROOT/pages/Installing_Packager_Tools.adoc @@ -0,0 +1,60 @@ += Installing Packager Tools +:toc: + +== Installing + +The `fedora-packager` package provides tools to help you setup and work with Fedora. +It will bring in everything necessary for general packaging work. +https://pagure.io/FedoraReview[fedora-review] automates many tasks related to package review. +Run the following: + +---- +$ sudo dnf install fedora-packager fedora-review +---- + +== Configuration + +=== .fedora.upn + +Some tools that use the Fedora client certificate +read `+~/.fedora.upn+` to determine the FAS username. +To setup this configuration file, do: + +---- +$ echo YOUR_FAS_ID > ~/.fedora.upn +---- + +=== Ssh key + +You also must have an ssh key configured in the +https://accounts.fedoraproject.org/[Fedora Accounts System] +to be able to make changes to any package, including your own. +`fedpkg` will expect the correct ssh key to be available in your keyring. +See wiki page https://fedoraproject.org/wiki/Cryptography#OpenSSH[Cryptography: OpenSSH] +for more information. + +== Acquiring Kerberos ticket + +Koji uses Kerberos for authentication. +To acquire valid Kerberos ticket, do: + +---- +$ KRB5_TRACE=/dev/stdout kinit @FEDORAPROJECT.ORG +---- + +Here, `FEDORAPROJECT.ORG` must be in capital case. + +Kerberos tickets have an expiration time, so `kinit` needs to be periodically re-issued. + +See https://fedoraproject.org/wiki/Infrastructure/Kerberos[Infrastructure/Kerberos] +for more information about the Fedora Kerberos setup. + +=== Configuring Mock + +To be able to test the build procedure in a clean chroot with +https://rpm-software-management.github.io/mock/[Mock], +you need to configure your account to be a member of the `mock` group: + +---- +$ sudo usermod -a -G mock +---- diff --git a/modules/ROOT/pages/Joining_the_Package_Maintainers.adoc b/modules/ROOT/pages/Joining_the_Package_Maintainers.adoc index 91567d1..17bb418 100644 --- a/modules/ROOT/pages/Joining_the_Package_Maintainers.adoc +++ b/modules/ROOT/pages/Joining_the_Package_Maintainers.adoc @@ -150,84 +150,9 @@ git config --global user.email johndoe@example.com .... [#install_the_developer_client_tools] -=== Install the developer client tools +=== Install Packager Tools -To build Packages for the Fedora Collection or EPEL -n the Fedora build system -you need xref:Using_the_Koji_Build_System.adoc[Koji]. - -The package provides tools to help you setup and work with fedora. -It will bring in everything necessary for general packaging work. -Run the following as root: - -.... -dnf install fedora-packager -.... - -After installation set your Fedora Account System username in -(do this as your normal user, not root). -You can do this via: - -.... -echo "yourfasid" > ~/.fedora.upn -.... - -(replacing `yourfasid`, of course.) - -You can now use `koji` to try to build your RPM packages -in the Fedora build system, -even on platforms or Fedora versions you don't have. -Note that you can (and definitely should) -test out builds ("scratch" builds) -even before your package has been approved -and you have been sponsored. -A simple way to do a scratch build using koji -is to do this at the command line: - -.... -koji build --scratch TARGET path_to_source_RPM -.... - -Where `TARGET` is a distribution keyword such as `f{MAJOROSVER}` -(for Fedora {MAJOROSVER}). -You can run `koji list-targets` to see all targets. -To build for the next release (rawhide), _do not_ use `dist-rawhide` -— use `fX` where X is one more than the latest stable or branched release. - -* Note that you need to supply the _path_ to the source RPM -(which ends in .src.rpm), -and *not* a URL. -(If you only have the spec file, -use `rpmbuild --nodeps -bs SPECFILE` -to create the new source RPM). - -Your koji builds can only depend on packages -that are actually in the `TARGET` distribution repository. -Thus, you can't use koji to build for released distributions -if your package depends on other new packages -that https://fedoraproject.org/wiki/Bodhi[Bodhi] hasn't released yet. -You _can_ use koji to build for rawhide -(the next unreleased version), -even if it depends on other new packages, -as long as the other packages were built for Rawhide -as described below. -If you need to build against a package -that is not yet a stable released update, -you can https://pagure.io/releng/new_issue[file a ticket with rel-eng] -and request that that package is added as a buildroot override. -For packages in EPEL, -you have to use the component `epel` -to get the request to the right persons. - -You can learn more about koji via: - -.... -koji --help # General help -koji --help-commands # list of koji commands -koji COMMAND --help # help on command COMMAND -.... - -xref:Using_the_Koji_Build_System.adoc[Using the Koji build system] has more information about using Koji. +Follow xref:Installing_Packager_Tools.adoc[Installing Packager Tools]. [#find_software] == Finding software you wish to maintain for Fedora diff --git a/modules/ROOT/pages/Package_Maintenance_Guide.adoc b/modules/ROOT/pages/Package_Maintenance_Guide.adoc index 2dea99d..fc6dd96 100644 --- a/modules/ROOT/pages/Package_Maintenance_Guide.adoc +++ b/modules/ROOT/pages/Package_Maintenance_Guide.adoc @@ -19,28 +19,9 @@ You may have been looking for, or also be interested in: * https://docs.fedoraproject.org/en-US/packaging-guidelines/[Packaging Guidelines] [#installing_fedpkg_and_doing_initial_setup] -== Installing _fedpkg_ and doing initial setup +== Installing Packager Tools -Start by installing `fedpkg` with `dnf install fedpkg`. -This will be your primary interface to the packaging system. - -You also must have an ssh key configured in the https://accounts.fedoraproject.org/[Fedora Accounts System] -to be able to make changes to any package -(including your own). -`fedpkg` will expect the correct ssh key to be available in your keyring. - -Before uploading sources with `new-sources` and `upload` -and building packages in Koji, with `build` for example, -you have to get your Kerberos credential first with `kinit`, e.g. - -.... -kinit [FAS name]@FEDORAPROJECT.ORG -.... - -Keep `FEDORAPROJECT.ORG` in capital case. - -Set your Fedora Account System username in file `~/.fedora.upn`. -You can do this via `echo "FAS_USERNAME" > ~/.fedora.upn`. +Follow xref:Installing_Packager_Tools.adoc[Installing Packager Tools]. [#common_fedpkg_commands] == Common fedpkg commands diff --git a/modules/ROOT/pages/Packaging_Tutorial_GNU_Hello.adoc b/modules/ROOT/pages/Packaging_Tutorial_GNU_Hello.adoc index df8cd17..e60903c 100644 --- a/modules/ROOT/pages/Packaging_Tutorial_GNU_Hello.adoc +++ b/modules/ROOT/pages/Packaging_Tutorial_GNU_Hello.adoc @@ -27,28 +27,9 @@ It should, however, work also for other releases. Just replace strings like `f{MAJOROSVER}` with your release number. [#dev_env] -== Development Environment +== Installing Packager Tools -To build RPMs for Fedora we need a set of development tools. - ----- -$ sudo dnf install fedora-packager ----- - -To be able to test the build procedure in a clean chroot -you need to configure your non-privileged account to be a member of the `mock` group: - ----- -$ sudo usermod -a -G mock ----- - -This is the only setup requiring `+sudo+` privileges. -The remaining work should be done from your regular, non-privileged account, -or even from a separate account created just for development work. -Modern RPM-based systems, including Fedora, -are set up to build packages purely from within a non-privileged account. -Later in the tutorial, -installing the pacakge to test it also requires `+sudo+` privileges. +Follow xref:Installing_Packager_Tools.adoc[Installing Packager Tools]. [#building] == Building the RPM diff --git a/modules/ROOT/pages/Using_the_Koji_Build_System.adoc b/modules/ROOT/pages/Using_the_Koji_Build_System.adoc index 64847c6..89172f4 100644 --- a/modules/ROOT/pages/Using_the_Koji_Build_System.adoc +++ b/modules/ROOT/pages/Using_the_Koji_Build_System.adoc @@ -10,38 +10,19 @@ and get information about the buildsystem. Koji runs on top of Mock to build RPM packages for specific architectures and ensure that they build correctly. +You can use the `koji` command directly, or use `fedpkg`, +a script that interacts with the RPM Packaging system and other subsystems, +like `git` and `koji` itself. + There is also a https://fedoraproject.org/wiki/Zh/%E4%BD%BF%E7%94%A8Koji%E7%BC%96%E8%AF%91%E6%89%93%E5%8C%85%E7%B3%BB%E7%BB%9F[simplified Chinese edition]. [#installing_koji] === Installing Koji -[#koji_setup] -==== Koji Setup - -Before using Koji to build packages, -you must have the `fedora-packager` package installed: - -.... -dnf install fedora-packager -.... - -You must also have a valid kerberos ticket: - -.... -KRB5_TRACE=/dev/stdout kinit your_fas_username@FEDORAPROJECT.ORG -.... - -Here, `FEDORAPROJECT.ORG` must be in capital case. - -Store your FAS username (all lower case) in `~/.fedora.upn`. -This is not actually needed for Kerberos -but for other tools that use the Fedora client certificate -to determine the FAS username. - -For more information, see https://fedoraproject.org/wiki/Infrastructure/Kerberos[Kerberos setup]. +Follow xref:Installing_Packager_Tools.adoc[Installing Packager Tools]. [#koji_config] -==== Koji Config +=== Koji Config The global-local client configuration file for koji is `/etc/koji.conf`. You should not need to change this from the defaults @@ -49,10 +30,6 @@ for building Fedora packages. These allow you to use the primary build system as well as secondary arch build systems. -You can use the `koji` command directly, -or use `fedpkg`, a script that interacts with the RPM Packaging system and other subsystems, -like git and koji itself. - [#building_with_fedpkg_targets] === Building with fedpkg targets From a8f487dd15f4b1914afa64130d34e48e4f54e14f Mon Sep 17 00:00:00 2001 From: Otto Urpelainen Date: Feb 11 2022 21:28:03 +0000 Subject: [PATCH 2/3] Install tools in New Package Process for New Contributors It may be that a reader of this page does not have to tools installed. They are needed to follow the instructions, so a mention about needing them is added in the beginning. --- diff --git a/modules/ROOT/pages/New_Package_Process_for_New_Contributors.adoc b/modules/ROOT/pages/New_Package_Process_for_New_Contributors.adoc index 0bc670b..0752ced 100644 --- a/modules/ROOT/pages/New_Package_Process_for_New_Contributors.adoc +++ b/modules/ROOT/pages/New_Package_Process_for_New_Contributors.adoc @@ -7,6 +7,11 @@ This is a long version of the New Package Process, containing more details so new contributors can follow it more easily. Also the mandatory xref:How_to_Get_Sponsored_into_the_Packager_Group.adoc[sponsoring] step is included. +[#install_tools] +== Install Packager Tools + +Follow xref:Installing_Packager_Tools.adoc[Installing Packager Tools]. + [#check] == Check if the package already exists From 1b7574bba41050a2b2e093ab313e7ec97b486629 Mon Sep 17 00:00:00 2001 From: Otto Urpelainen Date: Feb 11 2022 21:28:03 +0000 Subject: [PATCH 3/3] Remove mention of .fedora.upn It seems that no tool needed in package maintenance actually uses file .fedora.upn. Thus there is no need to mention it in the tool installation page. --- diff --git a/modules/ROOT/pages/Installing_Packager_Tools.adoc b/modules/ROOT/pages/Installing_Packager_Tools.adoc index d13bdd0..40ba262 100644 --- a/modules/ROOT/pages/Installing_Packager_Tools.adoc +++ b/modules/ROOT/pages/Installing_Packager_Tools.adoc @@ -14,16 +14,6 @@ $ sudo dnf install fedora-packager fedora-review == Configuration -=== .fedora.upn - -Some tools that use the Fedora client certificate -read `+~/.fedora.upn+` to determine the FAS username. -To setup this configuration file, do: - ----- -$ echo YOUR_FAS_ID > ~/.fedora.upn ----- - === Ssh key You also must have an ssh key configured in the