From 4fc283549ffd18092c75cc42ed3a586860cbe49e Mon Sep 17 00:00:00 2001 From: Pierre-Yves Chibon Date: Apr 10 2018 01:00:59 +0000 Subject: [PATCH 1/4] Move olds/current docs to an old folder for now Signed-off-by: Pierre-Yves Chibon --- diff --git a/content/en-US/join-the-package-collection-maintainers.adoc b/content/en-US/join-the-package-collection-maintainers.adoc deleted file mode 100644 index 7964f27..0000000 --- a/content/en-US/join-the-package-collection-maintainers.adoc +++ /dev/null @@ -1,480 +0,0 @@ -[[contributing-roles]] -= Contributing roles - -[cols="",] -|======================================================================= -|image:Join_OSDeveloper.png[Join_OSDeveloper.png,title="fig:Join_OSDeveloper.png"] + -link:Join#OS_Developer[OS Developer] -|======================================================================= - -[[how-to-join-the-fedora-package-collection-maintainers]] -= How to join the Fedora Package Collection Maintainers? - -So, you have decided to become a package maintainer in the Fedora -Project? This guide will lead you through your first package submission. - -file:fedora-submit-package.png[750x214px] - -[[becoming-a-fedora-package-collection-maintainer]] -== Becoming a Fedora Package Collection Maintainer - -[[read-the-guidelines]] -=== Read the Guidelines - -If you don't know how to create an RPM package, refer to the tutorial at -How_to_create_a_GNU_Hello_RPM_package or the more advanced and much more -detailed link:how to create an RPM package[how to create an RPM -package]. - -Read the Packaging:Guidelines[ Packaging Guidelines] and -Packaging:NamingGuidelines[ Package Naming Guidelines] . - -You need to be thoroughly familiar with these. They govern all package -submissions. If you have questions, ask on the Fedora List. - -[[create-a-bugzilla-account]] -=== Create a Bugzilla Account - -Make sure you have an account in https://bugzilla.redhat.com/[Red Hat -Bugzilla] . - -The email address that you use for your Bugzilla account should be the -same email address as you use in the link:#Get_a_Fedora_Account[ Fedora -Account System] for all things related to Fedora Packaging. - -[[create-a-fedora-account]] -=== Create a Fedora Account - -Create an account in the link:Infrastructure/AccountSystem[Fedora -Account System] (this is _not_ the same as the Bugzilla account) - -1. Visit the account system home: -https://admin.fedoraproject.org/accounts/ -2. Click on 'New account' and fill in the blanks. Note that the email -you give should be the same as the one you gave Bugzilla. This allows -the system to link privileges between the two accounts. -3. After you create your account, please be sure to sign the CLA (if -you click on the "My Account" link in the top right, you should see CLA: -CLA Done). -4. You will also need to upload a public RSA SSH key. You need to use -the matching private key to access Fedora machines via SSH. You can read -more about this link:Cryptography[ here]. - -[[join-the-important-mailing-lists]] -=== Join the important Mailing Lists - -You must join the fedora mailing list. It is a low traffic announcements -only list, where important development information is posted. - -You can join the fedora mailing list, where discussions about the -development of Fedora are held. This is a high traffic mailing list. - -You can also consider joining the mailing list -- The commits mailing -list gets notifications on all commits in any package in the Fedora -repository. This is a very high traffic mailing list. The Fedora package -database sends commit mails for packages you (co-)maintain. - -Another mailing list you might consider (at least to view the archives) -is . This is the mailing list of the link:Packaging/Committee[ Fedora -Packaging Committee], who determine the official packaging guidelines -for Fedora projects. - -[[ensure-the-software-you-wish-to-package-is-suitable]] -=== Ensure the software you wish to package is suitable - -The package you are submitting can be of any free and open source -project that is not already packaged in Fedora. Before creating your -package, make sure that the software is not already in the Fedora -repository, or waiting for review. - -* Search the https://apps.fedoraproject.org/packages/[Fedora packages] -for packages already in the repository. -* Search in the http://fedoraproject.org/PackageReviewStatus/[Review -Tracker] for packages under review. -* Also check the link:Deprecated_packages[ deprecated packages] list. -* Be aware of link:forbidden items[forbidden items]. - -[[understand-your-responsibilities]] -=== Understand your responsibilities - -Software components included in Fedora need to be maintained actively, -and bugs - especially security issues - need to be fixed in a timely -manner. As a Fedora package maintainer, it is your primary -link:Package_maintainer_responsibilities[ responsibility] to ensure -this. We encourage you to get -link:Policy_for_encouraging_comaintainers_of_packages[ co-maintainers] -and seek the help of the Fedora community via the development mailing -list whenever needed. - -[[read-other-submissions]] -=== Read Other Submissions - -Read some other package submissions to learn about packaging and gain -familiarity with the process and requirements. - -One way of doing this is to join the mailing list;All comments on Fedora -package reviews are sent to this (read-only from your point of view) -list. - -[[configure-your-git]] -=== Configure Your Git - -First thing to do when you set up Fedora packaging is to configure your -user name and email address for Git. These are linked in each commit you -do to Fedora packages. - --------------------------------------------------- -git config --global user.name "John Doe" -git config --global user.email johndoe@example.com --------------------------------------------------- - -[[install-the-developer-client-tools]] -=== Install the developer client tools - -To build Packages for the Fedora Collection or EPEL in the Fedora build -system you need link:Using_the_Koji_build_system[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 run the following as your user (not root) to -link:Using_the_Koji_build_system#Fedora_Account_System_.28FAS2.29_Setup[setup -your koji client configuration]: - -`fedora-packager-setup` - -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 f25 (for Fedora 25). You can -run "koji list-targets" to see all targets. To build for the next -release (rawhide), _don't_ 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 link: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 the "rawhide" -as described below. If you need to build against a package that is not -yet a stable released update, you can file a ticket with rel-eng at: -https://fedorahosted.org/rel-eng/newticket and request that that package -be 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` - -link:Using the Koji build system[Using the Koji build system] has more -information about using Koji. - -[[make-a-package]] -=== Make a Package - -* If you don't know how to create an RPM package, see the -link:How to create an RPM package[How to create an RPM package]. -* Make sure that your package meets the Packaging:Guidelines[ Packaging -Guidelines] and Packaging:NamingGuidelines[ PackageNamingGuidelines] . -* Be aware of the Packaging:ReviewGuidelines[ Package Review Guidelines] -(they will be used during the package review). -* Make sure your package builds. This is surprisingly important, because -a significant number of submissions don't. - -[[upload-your-package]] -=== Upload Your Package - -Upload your SRPM and SPEC files onto the Internet somewhere so that -others can retrieve them. This can be anywhere accessible by a URL, but -it is important that the files be directly accessible, not hidden behind -some service that makes people wait to download things or redirects -through advertising pages. - -If you want to make ad-hoc builds available for users while you are -getting the package into the official repositories, consider using -https://copr.fedorainfracloud.org[Copr]. It is a light weight automated -build system that can create repositories using the SRPM you upload. You -can use this Copr space to point reviewers to your src.rpm and spec. - -[[create-your-review-request]] -=== Create Your Review Request - -Fill out this form: -https://bugzilla.redhat.com/bugzilla/enter_bug.cgi?product=Fedora&format=fedora-review. - -* Before submitting your request, be sure there’s not a previous request -for the same package. There is a convenient search box on the -http://fedoraproject.org/PackageReviewStatus/[package review status -page]. -* Make sure that you put the *name of the package* (excluding version -and release numbers) in the '`Review Summary`' field, along with a very -*brief summary* of what the package is. -* Put a *description* of your package (usually, this can be the same -thing as what you put in the spec %description) in the -'`Review Description`' field. Include the *URLs* to your *SRPM* and -*SPEC* files. -* Explain in the ticket that this is your first package and you need a -sponsor. Also include any information that may help prospective -sponsors. If you've been active in other review work, include links. If -you're the upstream maintainer, be sure to say so. -* For bonus points, include a link to a successful koji build so that -everyone knows you did all of your homework. - -The review process is described in detail on the -link:Package Review Process[ Package Review Process] page. - -[[inform-upstream]] -=== Inform Upstream - -Fedora as a project prefers to link:Staying_close_to_upstream_projects[ -stay close to upstream]. Inform the developers that you are packaging -the software. You can do that by sending them an email introducing -yourself and pointing out the review request. This sets up the stage for -future conversations. They will usually advertise the fact that their -software is now part of Fedora or might want to inform you of important -bugs in the existing release, future roadmaps etc. - -[[introduce-yourself]] -=== Introduce yourself - -When a new package maintainer joins the Fedora Project, we request that -he/she introduces themselves on the Fedora mailing list. To sign up for -the list, visit the list's signup page. The primary purpose of this is -to begin the process of building trust by allowing the Fedora community -members to get to know you a bit more and increase the chances of your -review request being processed sooner. - -We want to break anonymity and foster real-world community within the -project. You are under no obligation to reveal personal secrets. The -objective is to establish a level of trust with yourself and the other -members of the project. But you should at least use your real name when -communicating with us. Also a brief description of who you are, your -motivations and perhaps a description of the software you have submitted -for review is advisable. - ------------------------------------------------------------- - -Subject: Self Introduction: - -Body: Add any information you believe is applicable -including past experience in free and open source projects, -a link to the review request you have filed and -a brief description of yourself. You can also post -your GPG key information if you want to. ------------------------------------------------------------- - -[[watch-for-feedback]] -=== Watch for Feedback - -Watch the Bugzilla report for your first package. You should get -notifications of changes by email. Fix any blockers that the reviewer(s) -point out. - -[[get-sponsored]] -=== Get Sponsored - -When the package is APPROVED by the reviewer, you must separately obtain -member sponsorship in order to check in and build your package. -Sponsorship is not automatic and may require that you further -participate in other ways in order to demonstrate your understanding of -the packaging guidelines. Key to becoming sponsored is to convince an -existing sponsor-level member that you understand and follow the -project's guidelines and processes. - -See link:how to get sponsored into the packager group[how to get -sponsored into the packager group] for more information on the process -of becoming sponsored. - -Your sponsor can add you to the packager group. You should receive email -confirmation of your sponsorship. - -[[add-package-to-source-code-management-scm-system-and-set-owner]] -=== Add Package to Source Code Management (SCM) system and Set Owner - -Before proceeding, please sync your account by login on -https://src.fedoraproject.org/ using your FAS credentials. - -If you are becoming a maintainer for a new package, instead of being a -co-maintainer, use the https://pagure.io/fedrepo_req[fedrepo-req] tool -to request a new git repository for your package. The README file for -fedrepo-req has instructions for configuring and using the tool. - -The request will be reviewed and processed by an admin, usually within -24 hours. Once the ticket is processed, you will have access to commit -and build the package. - -[[check-out-the-module]] -=== Check out the module - -You _could_ check out your module now, but before doing that, consider -doing `mkdir ~/fedora-scm ; cd ~/fedora-scm` - that way, all your files -are inside a single directory. Also, run `ssh-add`, so that you won't -have to keep typing in your key password. - -Now you are ready to checkout your module from the SCM: - ---------------------------- - fedpkg clone ---------------------------- - -Where `` should be replaced with the name of your package. - -[[test-your-package]] -=== Test Your Package - -Refer to Using_Mock_to_test_package_builds and -Using_the_Koji_build_system#Scratch_Builds for more information on -testing your package. Mock uses your local system while Koji command -line tool uses the Fedora build system server. - -[[import-commit-and-build-your-package]] -=== Import, commit, and build your package - -Now that you've checked out your (empty) package module with fedpkg, cd -into the module's master branch: - -`cd ` - -Run fedpkg to import the contents of the SRPM into the SCM: - -`fedpkg import PATH_TO_SRPM` - -`# Review Changes, press 'q' to stop; Revert with: git reset --hard HEAD` + -`git commit -m "Initial import (#XXXXXX)."` + -`git push` + -`fedpkg build` - -Obviously, replace `PATH_TO_SRPM` with the full path (not URL) to your -approved SRPM, and `XXXXXX` with the package review bug number. - -This imports into, commits, and builds only the *master* -(link:Releases/Rawhide[Rawhide]) branch. - -If the push fails with this kind of message: - -`W access for why DENIED to YOUR_ACCOUNT` + -`fatal: The remote end hung up unexpectedly` + -`Could not push: Command '['git', 'push']' returned non-zero exit status 128` - -Then you don't have the necessary rights to modify that package branch; -view https://src.fedoraproject.org/rpms/PACKAGE_NAME to request those -rights. - -For more information on using the Fedora package maintenance system, see -the link:Package maintenance guide[Package maintenance guide]. - -[[update-your-branches-if-desired]] -=== Update Your Branches (if desired) - -Branches are `f`# (formerly `F-`# and before that `FC-`#), `master`, -etc. So _f_ is the branch for Fedora . - -To switch to a branch first: - -`fedpkg switch-branch BRANCH (e.g. f``)` - -Merge the initial commit from master, creating an identical commit in -the branch: - -`git merge master` - -Push the changes to the server: - -`git push` - -Build the package: - -`fedpkg build` - -If there is another branch to work with repeat "To switch to a branch" -and import and commit to each branch. - -If everything goes well, it should queue up your branch for building, -the package will cleanly build, and you're done! - -If it fails to build, the build system will send you an email to report -the failure and show you to the logs. Commit any needed changes to git, -bump the SPEC release number, and request a new build. - -[[submit-package-as-update-in-bodhi]] -=== Submit Package as Update in Bodhi - -The Fedora update system called Bodhi is used for pushing updates, -classifying packages etc. Do not submit Rawhide (master branch) builds -via Bodhi. - -You can push an update using Bodhi via the command line using this in -each branch: - -`fedpkg update` - -See the link:Package_update_HOWTO[update submission guide] for more -details. - -[[make-the-package-available-in-comps-files]] -=== Make the package available in "comps" files - -If appropriate for the package, make it available in "comps" files so -that it can be selected during installation and included in dnf's|yum's -package group operations. See link:PackageMaintainers/CompsXml[How to -use and edit comps.xml for package groups] for more info. - -[[watch-for-updates]] -=== Watch for updates - -Fedora has infrastructure available for monitoring new upstream releases -of the software you are packaging. Refer to -link:Upstream Release Monitoring[Upstream Release Monitoring] for more -details. - -[[getting-help]] -== Getting Help - -We know that this process can be as clear as mud sometimes, and we're -always trying to make it better. If you run into any problems, or have -any questions, please ask on the mailing list or in on freenode.net. - -[[getting-a-new-package-into-fedora-package-collection-for-existing-maintainers]] -== Getting a new package into Fedora Package Collection for existing -maintainers - -If you already maintain a package in Fedora and want to maintain -another, follow the -link:new package process for existing contributors[new package process -for existing contributors] . - -[[one-off-contributions]] -= One-off contributions - -Changes to https://src.fedoraproject.org/browse/projects/[existing -packages] can be suggested by submitting -https://docs.pagure.org/pagure/usage/pull_requests.html[pull requests]. -You must have a -link:Join_the_package_collection_maintainers#Create_a_Fedora_Account[Fedora -account] to create a pull request. - -If https://pagure.io/fedora-infrastructure/issue/6361[your account is -not in the 'packager' group, you cannot push changes to forks on -src.fedoraproject.org] so you must use an external Git hosting platform -(e.g. https://pagure.io/new) and use -https://docs.pagure.org/pagure/usage/pull_requests.html#remote-git-to-pagure-pull-request[remote -pull-requests]. - -Category:Package Maintainers[Category:Package Maintainers] Category:Join diff --git a/content/en-US/new-package-process-for-existing-contributors.adoc b/content/en-US/new-package-process-for-existing-contributors.adoc deleted file mode 100644 index d2a4a72..0000000 --- a/content/en-US/new-package-process-for-existing-contributors.adoc +++ /dev/null @@ -1,113 +0,0 @@ -= new package process for existing contributors -This is a short version of the PackageMaintainers/Join document, -streamlined to show how existing contributors can make new packages. - -*Step 1:* Read the Packaging:Guidelines[ Packaging Guidelines] and -Packaging:NamingGuidelines[ Package Naming Guidelines] . Really. Be -comfortable with them. + -*Step 2:* Make a package. - -* You should make sure that it is a new package. A list of existing -packages in Fedora Packages is here: -https://src.fedoraproject.org/projects/rpms/* -* Some information on how to create an RPM package is in the -link:PackageMaintainers/CreatingPackageHowTo[ Creating Package HOWTO] -* Make sure that your package meets the Packaging:Guidelines[ Packaging -Guidelines] and Packaging:NamingGuidelines[ Package Naming Guidelines] -* Be aware of Forbidden_items and Packaging:ReviewGuidelines[ Package -Review Guidelines] (they will be used during the package review) - -*Step 3:* Upload your SRPM and SPEC files onto the internet somewhere. + -* If you have already got a Fedora Account then you can use your storage -at http://fedorapeople.org for this. *Step 4:* Make sure you have a -bugzilla account at bugzilla.redhat.com + -*Step 5:* Fill out this form: -https://bugzilla.redhat.com/bugzilla/enter_bug.cgi?product=Fedora&format=fedora-review - -* Make sure you put the name of the package in the Review Summary field, -along with a very brief summary of what it is -* Make sure that you put the URL paths for the SPEC file and the SRPM -file in the Review Description -* Put a description of your package (usually, this can be the same thing -as what you put in the spec %description) in Review Description -* The review process is described in detail here: -Packaging:ReviewGuidelines[ Package Review Guidelines] - -*Step 6:* Watch the bugzilla report for your first package (you created -this in step 5). Fix any blockers that the reviewer(s) point out. + -*Step 7:* When the package is approved by the reviewer, request a git -module and branches using -`fedpkg --module-name PACKAGE request-repo TICKET` and -`fedpkg --module-name PACKAGE request-branch BRANCH` (see -https://fedoraproject.org/wiki/Changes/fedrepo-req-to-fedpkg[1]) + -* Please wait until the request is approved. *Step 8:* Once the request -is approved, checkout the git module (details -link:Join_the_package_collection_maintainers#Check_out_the_module[here]) - -* Once you have the git module, checkout your module from git. Refer to -the link:Package maintenance guide[Package maintenance guide] -* It is probably a good idea to make a "git" toplevel directory, then -check-out your files inside of that. -* If your package is named foobar, this is done with: fedpkg clone -foobar - -*Step 9:* Import your srpm - -* First kinit username@FEDORAPROJECT.ORG -* Then you can import the approved SRPM into master branch by running -` fedpkg import libfoo-x.x.x.src.rpm; git commit -m "Initial import (#nnnnnn)."` -(where nnnnnn is your Bugzilla package review bug number). -* Obviously, replace libfoo-x.x.x.src.rpm with the full path to your -approved SRPM. -* You should see it upload the sources, and finish successfully. If you -didn't set up ssh-agent it will ask often for your ssh-key passphrase. -This is normal. -* Now run git push to get the final versions in your master branch. - -*Step 10:* You can now import the package to your branches (which you -has requested in Step 7) too - -* The quickest way to do this is to use `fedpkg switch-branch BRANCH` to -switch the branch (where BRANCH can be "f13" and so on). -* Now you can `git merge master`. This will get .spec file, .gitignore -and source file together with any patches and other files from master -branch and create identical commit. -* Previous step already created commit for you, now you can push the -results using `fedpkg push` or `git push`. - -*Step 11:* Request builds - -* For each branch that you'd like to request a build for, switch using -fedpkg switch-branch and run: `fedpkg build` -* If everything goes well, it should queue up your branch for building, -the package will cleanly build, and you're done! -* If it fails to build, the buildsystem will send you an email to report -the failure and link you to the logs. Commit any needed changes to git, -bump the spec release number and request a new build. - -*Step 12:* Close the bugzilla ticket (assuming that the package built -successfully) - -* You should close it with resolution NEXTRELEASE or RAWHIDE, depending -on where you built the package. The resolution field will appear after -you set the status field to CLOSED. - -*Step 13:* If this package will be built for any version of Fedora that -is already released please submit it for inclusion in the -'fedora-updates' repository for those versions of Fedora. See -link:Package_update_HOWTO#Later_Branched_and_stable_releases[the update -submission guide] for more details. + -*Step 14:* Add the package to the link:PackageMaintainers/CompsXml[comps -file(s)] if appropriate. + -*Step 15:* Consider enabling link:Upstream Release Monitoring[Upstream -Release Monitoring] for the package. - -We know that this process can be as clear as mud sometimes, we're always -trying to make it better. If you run into any problems, or have any -questions, please ask on fedora development list. + - http://lists.fedoraproject.org/pipermail/devel/ - -There is a helpful link:Package maintenance guide[Package maintenance -guide] which may also be of use. - -Category:Package Maintainers[Category:Package Maintainers] diff --git a/content/en-US/old/join-the-package-collection-maintainers.adoc b/content/en-US/old/join-the-package-collection-maintainers.adoc new file mode 100644 index 0000000..7964f27 --- /dev/null +++ b/content/en-US/old/join-the-package-collection-maintainers.adoc @@ -0,0 +1,480 @@ +[[contributing-roles]] += Contributing roles + +[cols="",] +|======================================================================= +|image:Join_OSDeveloper.png[Join_OSDeveloper.png,title="fig:Join_OSDeveloper.png"] + +link:Join#OS_Developer[OS Developer] +|======================================================================= + +[[how-to-join-the-fedora-package-collection-maintainers]] += How to join the Fedora Package Collection Maintainers? + +So, you have decided to become a package maintainer in the Fedora +Project? This guide will lead you through your first package submission. + +file:fedora-submit-package.png[750x214px] + +[[becoming-a-fedora-package-collection-maintainer]] +== Becoming a Fedora Package Collection Maintainer + +[[read-the-guidelines]] +=== Read the Guidelines + +If you don't know how to create an RPM package, refer to the tutorial at +How_to_create_a_GNU_Hello_RPM_package or the more advanced and much more +detailed link:how to create an RPM package[how to create an RPM +package]. + +Read the Packaging:Guidelines[ Packaging Guidelines] and +Packaging:NamingGuidelines[ Package Naming Guidelines] . + +You need to be thoroughly familiar with these. They govern all package +submissions. If you have questions, ask on the Fedora List. + +[[create-a-bugzilla-account]] +=== Create a Bugzilla Account + +Make sure you have an account in https://bugzilla.redhat.com/[Red Hat +Bugzilla] . + +The email address that you use for your Bugzilla account should be the +same email address as you use in the link:#Get_a_Fedora_Account[ Fedora +Account System] for all things related to Fedora Packaging. + +[[create-a-fedora-account]] +=== Create a Fedora Account + +Create an account in the link:Infrastructure/AccountSystem[Fedora +Account System] (this is _not_ the same as the Bugzilla account) + +1. Visit the account system home: +https://admin.fedoraproject.org/accounts/ +2. Click on 'New account' and fill in the blanks. Note that the email +you give should be the same as the one you gave Bugzilla. This allows +the system to link privileges between the two accounts. +3. After you create your account, please be sure to sign the CLA (if +you click on the "My Account" link in the top right, you should see CLA: +CLA Done). +4. You will also need to upload a public RSA SSH key. You need to use +the matching private key to access Fedora machines via SSH. You can read +more about this link:Cryptography[ here]. + +[[join-the-important-mailing-lists]] +=== Join the important Mailing Lists + +You must join the fedora mailing list. It is a low traffic announcements +only list, where important development information is posted. + +You can join the fedora mailing list, where discussions about the +development of Fedora are held. This is a high traffic mailing list. + +You can also consider joining the mailing list -- The commits mailing +list gets notifications on all commits in any package in the Fedora +repository. This is a very high traffic mailing list. The Fedora package +database sends commit mails for packages you (co-)maintain. + +Another mailing list you might consider (at least to view the archives) +is . This is the mailing list of the link:Packaging/Committee[ Fedora +Packaging Committee], who determine the official packaging guidelines +for Fedora projects. + +[[ensure-the-software-you-wish-to-package-is-suitable]] +=== Ensure the software you wish to package is suitable + +The package you are submitting can be of any free and open source +project that is not already packaged in Fedora. Before creating your +package, make sure that the software is not already in the Fedora +repository, or waiting for review. + +* Search the https://apps.fedoraproject.org/packages/[Fedora packages] +for packages already in the repository. +* Search in the http://fedoraproject.org/PackageReviewStatus/[Review +Tracker] for packages under review. +* Also check the link:Deprecated_packages[ deprecated packages] list. +* Be aware of link:forbidden items[forbidden items]. + +[[understand-your-responsibilities]] +=== Understand your responsibilities + +Software components included in Fedora need to be maintained actively, +and bugs - especially security issues - need to be fixed in a timely +manner. As a Fedora package maintainer, it is your primary +link:Package_maintainer_responsibilities[ responsibility] to ensure +this. We encourage you to get +link:Policy_for_encouraging_comaintainers_of_packages[ co-maintainers] +and seek the help of the Fedora community via the development mailing +list whenever needed. + +[[read-other-submissions]] +=== Read Other Submissions + +Read some other package submissions to learn about packaging and gain +familiarity with the process and requirements. + +One way of doing this is to join the mailing list;All comments on Fedora +package reviews are sent to this (read-only from your point of view) +list. + +[[configure-your-git]] +=== Configure Your Git + +First thing to do when you set up Fedora packaging is to configure your +user name and email address for Git. These are linked in each commit you +do to Fedora packages. + +-------------------------------------------------- +git config --global user.name "John Doe" +git config --global user.email johndoe@example.com +-------------------------------------------------- + +[[install-the-developer-client-tools]] +=== Install the developer client tools + +To build Packages for the Fedora Collection or EPEL in the Fedora build +system you need link:Using_the_Koji_build_system[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 run the following as your user (not root) to +link:Using_the_Koji_build_system#Fedora_Account_System_.28FAS2.29_Setup[setup +your koji client configuration]: + +`fedora-packager-setup` + +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 f25 (for Fedora 25). You can +run "koji list-targets" to see all targets. To build for the next +release (rawhide), _don't_ 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 link: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 the "rawhide" +as described below. If you need to build against a package that is not +yet a stable released update, you can file a ticket with rel-eng at: +https://fedorahosted.org/rel-eng/newticket and request that that package +be 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` + +link:Using the Koji build system[Using the Koji build system] has more +information about using Koji. + +[[make-a-package]] +=== Make a Package + +* If you don't know how to create an RPM package, see the +link:How to create an RPM package[How to create an RPM package]. +* Make sure that your package meets the Packaging:Guidelines[ Packaging +Guidelines] and Packaging:NamingGuidelines[ PackageNamingGuidelines] . +* Be aware of the Packaging:ReviewGuidelines[ Package Review Guidelines] +(they will be used during the package review). +* Make sure your package builds. This is surprisingly important, because +a significant number of submissions don't. + +[[upload-your-package]] +=== Upload Your Package + +Upload your SRPM and SPEC files onto the Internet somewhere so that +others can retrieve them. This can be anywhere accessible by a URL, but +it is important that the files be directly accessible, not hidden behind +some service that makes people wait to download things or redirects +through advertising pages. + +If you want to make ad-hoc builds available for users while you are +getting the package into the official repositories, consider using +https://copr.fedorainfracloud.org[Copr]. It is a light weight automated +build system that can create repositories using the SRPM you upload. You +can use this Copr space to point reviewers to your src.rpm and spec. + +[[create-your-review-request]] +=== Create Your Review Request + +Fill out this form: +https://bugzilla.redhat.com/bugzilla/enter_bug.cgi?product=Fedora&format=fedora-review. + +* Before submitting your request, be sure there’s not a previous request +for the same package. There is a convenient search box on the +http://fedoraproject.org/PackageReviewStatus/[package review status +page]. +* Make sure that you put the *name of the package* (excluding version +and release numbers) in the '`Review Summary`' field, along with a very +*brief summary* of what the package is. +* Put a *description* of your package (usually, this can be the same +thing as what you put in the spec %description) in the +'`Review Description`' field. Include the *URLs* to your *SRPM* and +*SPEC* files. +* Explain in the ticket that this is your first package and you need a +sponsor. Also include any information that may help prospective +sponsors. If you've been active in other review work, include links. If +you're the upstream maintainer, be sure to say so. +* For bonus points, include a link to a successful koji build so that +everyone knows you did all of your homework. + +The review process is described in detail on the +link:Package Review Process[ Package Review Process] page. + +[[inform-upstream]] +=== Inform Upstream + +Fedora as a project prefers to link:Staying_close_to_upstream_projects[ +stay close to upstream]. Inform the developers that you are packaging +the software. You can do that by sending them an email introducing +yourself and pointing out the review request. This sets up the stage for +future conversations. They will usually advertise the fact that their +software is now part of Fedora or might want to inform you of important +bugs in the existing release, future roadmaps etc. + +[[introduce-yourself]] +=== Introduce yourself + +When a new package maintainer joins the Fedora Project, we request that +he/she introduces themselves on the Fedora mailing list. To sign up for +the list, visit the list's signup page. The primary purpose of this is +to begin the process of building trust by allowing the Fedora community +members to get to know you a bit more and increase the chances of your +review request being processed sooner. + +We want to break anonymity and foster real-world community within the +project. You are under no obligation to reveal personal secrets. The +objective is to establish a level of trust with yourself and the other +members of the project. But you should at least use your real name when +communicating with us. Also a brief description of who you are, your +motivations and perhaps a description of the software you have submitted +for review is advisable. + +------------------------------------------------------------ + +Subject: Self Introduction: + +Body: Add any information you believe is applicable +including past experience in free and open source projects, +a link to the review request you have filed and +a brief description of yourself. You can also post +your GPG key information if you want to. +------------------------------------------------------------ + +[[watch-for-feedback]] +=== Watch for Feedback + +Watch the Bugzilla report for your first package. You should get +notifications of changes by email. Fix any blockers that the reviewer(s) +point out. + +[[get-sponsored]] +=== Get Sponsored + +When the package is APPROVED by the reviewer, you must separately obtain +member sponsorship in order to check in and build your package. +Sponsorship is not automatic and may require that you further +participate in other ways in order to demonstrate your understanding of +the packaging guidelines. Key to becoming sponsored is to convince an +existing sponsor-level member that you understand and follow the +project's guidelines and processes. + +See link:how to get sponsored into the packager group[how to get +sponsored into the packager group] for more information on the process +of becoming sponsored. + +Your sponsor can add you to the packager group. You should receive email +confirmation of your sponsorship. + +[[add-package-to-source-code-management-scm-system-and-set-owner]] +=== Add Package to Source Code Management (SCM) system and Set Owner + +Before proceeding, please sync your account by login on +https://src.fedoraproject.org/ using your FAS credentials. + +If you are becoming a maintainer for a new package, instead of being a +co-maintainer, use the https://pagure.io/fedrepo_req[fedrepo-req] tool +to request a new git repository for your package. The README file for +fedrepo-req has instructions for configuring and using the tool. + +The request will be reviewed and processed by an admin, usually within +24 hours. Once the ticket is processed, you will have access to commit +and build the package. + +[[check-out-the-module]] +=== Check out the module + +You _could_ check out your module now, but before doing that, consider +doing `mkdir ~/fedora-scm ; cd ~/fedora-scm` - that way, all your files +are inside a single directory. Also, run `ssh-add`, so that you won't +have to keep typing in your key password. + +Now you are ready to checkout your module from the SCM: + +--------------------------- + fedpkg clone +--------------------------- + +Where `` should be replaced with the name of your package. + +[[test-your-package]] +=== Test Your Package + +Refer to Using_Mock_to_test_package_builds and +Using_the_Koji_build_system#Scratch_Builds for more information on +testing your package. Mock uses your local system while Koji command +line tool uses the Fedora build system server. + +[[import-commit-and-build-your-package]] +=== Import, commit, and build your package + +Now that you've checked out your (empty) package module with fedpkg, cd +into the module's master branch: + +`cd ` + +Run fedpkg to import the contents of the SRPM into the SCM: + +`fedpkg import PATH_TO_SRPM` + +`# Review Changes, press 'q' to stop; Revert with: git reset --hard HEAD` + +`git commit -m "Initial import (#XXXXXX)."` + +`git push` + +`fedpkg build` + +Obviously, replace `PATH_TO_SRPM` with the full path (not URL) to your +approved SRPM, and `XXXXXX` with the package review bug number. + +This imports into, commits, and builds only the *master* +(link:Releases/Rawhide[Rawhide]) branch. + +If the push fails with this kind of message: + +`W access for why DENIED to YOUR_ACCOUNT` + +`fatal: The remote end hung up unexpectedly` + +`Could not push: Command '['git', 'push']' returned non-zero exit status 128` + +Then you don't have the necessary rights to modify that package branch; +view https://src.fedoraproject.org/rpms/PACKAGE_NAME to request those +rights. + +For more information on using the Fedora package maintenance system, see +the link:Package maintenance guide[Package maintenance guide]. + +[[update-your-branches-if-desired]] +=== Update Your Branches (if desired) + +Branches are `f`# (formerly `F-`# and before that `FC-`#), `master`, +etc. So _f_ is the branch for Fedora . + +To switch to a branch first: + +`fedpkg switch-branch BRANCH (e.g. f``)` + +Merge the initial commit from master, creating an identical commit in +the branch: + +`git merge master` + +Push the changes to the server: + +`git push` + +Build the package: + +`fedpkg build` + +If there is another branch to work with repeat "To switch to a branch" +and import and commit to each branch. + +If everything goes well, it should queue up your branch for building, +the package will cleanly build, and you're done! + +If it fails to build, the build system will send you an email to report +the failure and show you to the logs. Commit any needed changes to git, +bump the SPEC release number, and request a new build. + +[[submit-package-as-update-in-bodhi]] +=== Submit Package as Update in Bodhi + +The Fedora update system called Bodhi is used for pushing updates, +classifying packages etc. Do not submit Rawhide (master branch) builds +via Bodhi. + +You can push an update using Bodhi via the command line using this in +each branch: + +`fedpkg update` + +See the link:Package_update_HOWTO[update submission guide] for more +details. + +[[make-the-package-available-in-comps-files]] +=== Make the package available in "comps" files + +If appropriate for the package, make it available in "comps" files so +that it can be selected during installation and included in dnf's|yum's +package group operations. See link:PackageMaintainers/CompsXml[How to +use and edit comps.xml for package groups] for more info. + +[[watch-for-updates]] +=== Watch for updates + +Fedora has infrastructure available for monitoring new upstream releases +of the software you are packaging. Refer to +link:Upstream Release Monitoring[Upstream Release Monitoring] for more +details. + +[[getting-help]] +== Getting Help + +We know that this process can be as clear as mud sometimes, and we're +always trying to make it better. If you run into any problems, or have +any questions, please ask on the mailing list or in on freenode.net. + +[[getting-a-new-package-into-fedora-package-collection-for-existing-maintainers]] +== Getting a new package into Fedora Package Collection for existing +maintainers + +If you already maintain a package in Fedora and want to maintain +another, follow the +link:new package process for existing contributors[new package process +for existing contributors] . + +[[one-off-contributions]] += One-off contributions + +Changes to https://src.fedoraproject.org/browse/projects/[existing +packages] can be suggested by submitting +https://docs.pagure.org/pagure/usage/pull_requests.html[pull requests]. +You must have a +link:Join_the_package_collection_maintainers#Create_a_Fedora_Account[Fedora +account] to create a pull request. + +If https://pagure.io/fedora-infrastructure/issue/6361[your account is +not in the 'packager' group, you cannot push changes to forks on +src.fedoraproject.org] so you must use an external Git hosting platform +(e.g. https://pagure.io/new) and use +https://docs.pagure.org/pagure/usage/pull_requests.html#remote-git-to-pagure-pull-request[remote +pull-requests]. + +Category:Package Maintainers[Category:Package Maintainers] Category:Join diff --git a/content/en-US/old/new-package-process-for-existing-contributors.adoc b/content/en-US/old/new-package-process-for-existing-contributors.adoc new file mode 100644 index 0000000..d2a4a72 --- /dev/null +++ b/content/en-US/old/new-package-process-for-existing-contributors.adoc @@ -0,0 +1,113 @@ += new package process for existing contributors +This is a short version of the PackageMaintainers/Join document, +streamlined to show how existing contributors can make new packages. + +*Step 1:* Read the Packaging:Guidelines[ Packaging Guidelines] and +Packaging:NamingGuidelines[ Package Naming Guidelines] . Really. Be +comfortable with them. + +*Step 2:* Make a package. + +* You should make sure that it is a new package. A list of existing +packages in Fedora Packages is here: +https://src.fedoraproject.org/projects/rpms/* +* Some information on how to create an RPM package is in the +link:PackageMaintainers/CreatingPackageHowTo[ Creating Package HOWTO] +* Make sure that your package meets the Packaging:Guidelines[ Packaging +Guidelines] and Packaging:NamingGuidelines[ Package Naming Guidelines] +* Be aware of Forbidden_items and Packaging:ReviewGuidelines[ Package +Review Guidelines] (they will be used during the package review) + +*Step 3:* Upload your SRPM and SPEC files onto the internet somewhere. + +* If you have already got a Fedora Account then you can use your storage +at http://fedorapeople.org for this. *Step 4:* Make sure you have a +bugzilla account at bugzilla.redhat.com + +*Step 5:* Fill out this form: +https://bugzilla.redhat.com/bugzilla/enter_bug.cgi?product=Fedora&format=fedora-review + +* Make sure you put the name of the package in the Review Summary field, +along with a very brief summary of what it is +* Make sure that you put the URL paths for the SPEC file and the SRPM +file in the Review Description +* Put a description of your package (usually, this can be the same thing +as what you put in the spec %description) in Review Description +* The review process is described in detail here: +Packaging:ReviewGuidelines[ Package Review Guidelines] + +*Step 6:* Watch the bugzilla report for your first package (you created +this in step 5). Fix any blockers that the reviewer(s) point out. + +*Step 7:* When the package is approved by the reviewer, request a git +module and branches using +`fedpkg --module-name PACKAGE request-repo TICKET` and +`fedpkg --module-name PACKAGE request-branch BRANCH` (see +https://fedoraproject.org/wiki/Changes/fedrepo-req-to-fedpkg[1]) + +* Please wait until the request is approved. *Step 8:* Once the request +is approved, checkout the git module (details +link:Join_the_package_collection_maintainers#Check_out_the_module[here]) + +* Once you have the git module, checkout your module from git. Refer to +the link:Package maintenance guide[Package maintenance guide] +* It is probably a good idea to make a "git" toplevel directory, then +check-out your files inside of that. +* If your package is named foobar, this is done with: fedpkg clone +foobar + +*Step 9:* Import your srpm + +* First kinit username@FEDORAPROJECT.ORG +* Then you can import the approved SRPM into master branch by running +` fedpkg import libfoo-x.x.x.src.rpm; git commit -m "Initial import (#nnnnnn)."` +(where nnnnnn is your Bugzilla package review bug number). +* Obviously, replace libfoo-x.x.x.src.rpm with the full path to your +approved SRPM. +* You should see it upload the sources, and finish successfully. If you +didn't set up ssh-agent it will ask often for your ssh-key passphrase. +This is normal. +* Now run git push to get the final versions in your master branch. + +*Step 10:* You can now import the package to your branches (which you +has requested in Step 7) too + +* The quickest way to do this is to use `fedpkg switch-branch BRANCH` to +switch the branch (where BRANCH can be "f13" and so on). +* Now you can `git merge master`. This will get .spec file, .gitignore +and source file together with any patches and other files from master +branch and create identical commit. +* Previous step already created commit for you, now you can push the +results using `fedpkg push` or `git push`. + +*Step 11:* Request builds + +* For each branch that you'd like to request a build for, switch using +fedpkg switch-branch and run: `fedpkg build` +* If everything goes well, it should queue up your branch for building, +the package will cleanly build, and you're done! +* If it fails to build, the buildsystem will send you an email to report +the failure and link you to the logs. Commit any needed changes to git, +bump the spec release number and request a new build. + +*Step 12:* Close the bugzilla ticket (assuming that the package built +successfully) + +* You should close it with resolution NEXTRELEASE or RAWHIDE, depending +on where you built the package. The resolution field will appear after +you set the status field to CLOSED. + +*Step 13:* If this package will be built for any version of Fedora that +is already released please submit it for inclusion in the +'fedora-updates' repository for those versions of Fedora. See +link:Package_update_HOWTO#Later_Branched_and_stable_releases[the update +submission guide] for more details. + +*Step 14:* Add the package to the link:PackageMaintainers/CompsXml[comps +file(s)] if appropriate. + +*Step 15:* Consider enabling link:Upstream Release Monitoring[Upstream +Release Monitoring] for the package. + +We know that this process can be as clear as mud sometimes, we're always +trying to make it better. If you run into any problems, or have any +questions, please ask on fedora development list. + + http://lists.fedoraproject.org/pipermail/devel/ + +There is a helpful link:Package maintenance guide[Package maintenance +guide] which may also be of use. + +Category:Package Maintainers[Category:Package Maintainers] diff --git a/content/en-US/old/package-maintenance-guide.adoc b/content/en-US/old/package-maintenance-guide.adoc new file mode 100644 index 0000000..a2f49bd --- /dev/null +++ b/content/en-US/old/package-maintenance-guide.adoc @@ -0,0 +1,369 @@ += package maintainence guide +This page provides some basic instructions for day-to-day usage of the +http://git-scm.com/[git]-based package maintenance system for Fedora. It +is intended primarily for new and current Fedora package maintainers, +but does briefly link:#anon[cover anonymous read-only use of the +system]. It is not a guide to RPM packaging per se. Some pre-existing +knowledge of git may be useful, but is not a pre-requisite (in fact, +Fedora packaging can be a relatively painless introduction to it). + +You may have been looking for, or also be interested in: + +* link:How_to_create_an_RPM_package[Learning to create packages] +* link:Join_the_package_collection_maintainers[Becoming a package +maintainer] +* link:Package_update_HOWTO[Submitting package updates] +* link:New_package_process_for_existing_contributors[Adding a new +package to the repository] as an existing maintainer +* +link:PackageDB_admin_requests#Additional_branches_for_existing_packages[adding +a new release branch] to an existing package +* Packaging:Guidelines[The Packaging Guidelines] + +[[installing-fedpkg-and-doing-initial-setup]] +== Installing _fedpkg_ and doing initial setup + +Start by installing with . This will also install the tool, which will +be your primary interface to the packaging system. Run to configure your +machine for package maintenance. If you have run before, but wish to set +up a new machine, copy the files to the new system. + +You also must have an ssh key configured in the +https://admin.fedoraproject.org/accounts/[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) + +[[common-fedpkg-commands]] +== Common fedpkg commands + +This section lists typical fedpkg commands in a normal workflow, with +short descriptions. Longer explanations for each can be seen by clicking +the 'Show' links. In this workflow, we will be operating on the +link:Releases/Rawhide[Rawhide] branch of the package. + +* Check out a package: + +`fedpkg co ` + +`cd ` + +* Update your checked-out copy from the Fedora server: + +`fedpkg pull` + +* Retrieve the package sources: + +`fedpkg sources` + +* Make your changes to the package + +* Run the 'prep' stage (extract source, apply patches etc) within the +checkout directory: + +`fedpkg prep` + +* Do a local build of the current state: + +`fedpkg local` + +* Do a mock build of the current state: + +`fedpkg mockbuild` + +* Generate a .src.rpm from the current state: + +`fedpkg srpm` + +* Do a scratch build using koji: see +https://fedoraproject.org/wiki/Using_the_Koji_build_system#Scratch_Builds[Koji +scratch builds] +* Check changes you have made: + +`fedpkg diff` + +* Run some checks (rpmlint) on your package: + +`fedpkg lint` + +* Stage any small patches or new source files for commit: + +`git add (somefile)` + +* Upload new source files to the lookaside cache: + +`fedpkg new-sources` + +`fedpkg upload` + +* Switch to a different release branch: + +`fedpkg switch-branch ` + +* Generate git changelog from package changelog: + +`fedpkg clog` + +* Commit changes: + +`fedpkg commit (-F clog) (-p) (-c)` + +* Push changes: + +`fedpkg push` + +* Do an 'official' build of the latest pushed changes: + +`fedpkg build` + +* In the event you are working with a Docker +link:Changes/Layered_Docker_Image_Build_Service[Container Layered Image +Build] + +`fedpkg container-build` + +* Submit a package update for the latest build: + +`fedpkg update` + +[[typical-fedpkg-session]] +== Typical _fedpkg_ session + +A typical session may look like this: + +--------------------------------------------------------------------------- +fedpkg clone foo +cd foo +fedpkg sources +fedpkg new-sources foo-0.0.2.tar.bz2 +gedit foo.spec # change the required things in the specfile. + # rpmdev-bumpspec is useful for simple version updates +fedpkg mockbuild # check that the changes you made are correct +fedpkg diff +fedpkg lint +fedpkg commit -p -c # commit and push in one go +--------------------------------------------------------------------------- + +[[working-with-branches]] +== Working with branches + +Each Fedora release is represented by a branch in the git repository. +You can switch between them like this: + +`fedpkg switch-branch f` + +`fedpkg switch-branch f` + +`fedpkg switch-branch master` + +The _master_ branch is for link:Releases/Rawhide[Rawhide]. You can +maintain each branch entirely separately, if you like, laboriously +copying changes between them (so long as you always stay within the +link:Updates Policy[Updates Policy] requirements). However, git provides +us with several handy tools for working with branches. Here's an +example: This will 'merge' the changes from the _master_ (Rawhide) +branch to the f branch. git aficionados may note this is a somewhat +unusual workflow, but it is appropriate to the context of package +management. Remember, after pushing to and building for a stable release +or a link:Releases/Branched[Branched] release after +link:Updates Policy#Bodhi_enabling[Bodhi has been enabled], you will +have to link:Package_update_HOWTO[submit an update] before any other +Fedora users will see your build. + +Note that merges will only be sure to work cleanly so long as the +branches have not previously diverged. That is, if you do this: you may +encounter a _merge conflict_. + +Remember that git is a _collaborative_ system, and used as such in +Fedora package management. It is often the case that you must consider +changes made by others in working on a package, and consider how your +changes will affect others. + +[[resolving-merge-conflicts]] +=== Resolving merge conflicts + +This is a large topic and somewhat beyond the scope of this guide, but +we can give basic pointers. There are other good references in the +http://git-scm.com/book/en/Git-Branching-Basic-Branching-and-Merging[git +book] and at +https://help.github.com/articles/resolving-a-merge-conflict-from-the-command-line[github]. + +When you git merge and a conflict occurs you can edit the files that +have conflicts. Remove the conflict markers in the files and merge the +changes manually. Use or to inspect the changes against the pre-conflict +state and verify you are happy with the resolution. Then you can commit +the files with or . git will know if you have resolved the conflict by +checking that all the conflict markers have been removed. + +[[using-git-mergetool-to-resolve-conflicts]] +=== Using `git mergetool` to resolve conflicts + +Git provides a graphical diff program to help resolve conflicts. This +can be handy for visualizing what changes have occurred and dealing with +them as a set. + +[[requesting-special-dist-tags]] +== Requesting special dist tags + +When a change to a package affects a large number of dependencies (e.g. +all perl, python, ruby or ghc packages), requiring them to be rebuilt, +it may be better to initially do the builds in a special repository, so +that there is less disruption in Rawhide. + +If you think you have an update that falls under this case you can +request a special dist tag by filing a +https://fedorahosted.org/rel-eng/newticket[release engineering ticket]. +Someone from link:ReleaseEngineering[release engineering] will likely +want to discuss your needs to make sure this is really an appropriate +case (it's OK ask if you aren't sure) and that you get what you need. + +[[tips-and-tricks]] +== Tips and tricks + +[[using-fedpkg-anonymously]] +=== Using fedpkg anonymously + +You can use fedpkg like this: + +`fedpkg clone --anonymous ` + +to check out a package without requiring identification. Obviously, you +will not be able to push any changes to this repository, but it is +useful for non-packagers who simply want to examine a package, make +changes for their own use, and perhaps submit changes to a Fedora +developer. + +[[local-branch-names]] +=== Local branch names + +If you use git commands to branch and checkout directly, you can define +whatever local branch names you want. If you use , it will default to +creating the names used in the examples above. + +[[current-branch-and-state-in-shell-prompt]] +=== Current branch and state in shell prompt + +It is often helpful to know what branch you are working on at a glance. +You can add this information to your bash prompt with the information +link:Git_Quickref#Display_current_branch_in_bash[here]. + +[[importing-a-.src.rpm-to-update]] +=== Importing a .src.rpm to update + +The command usually used to initially populate a git package repository +from a .src.rpm that has been through the +link:Package Review Process[Package Review Process] can also be used to +update a normal working copy, if you have an old-school packaging +process to which you are particularly attached. Just run and it will +upload new tarballs into lookaside cache, update a working copy of the +last version found in git, and commit all changes. documents some other +parameters it can accept. + +[[making-changes-on-an-older-branch-without-breaking-the-upgrade-path]] +=== Making changes on an older branch without breaking the upgrade path + +Here is the scenario: you've built your package successfully on the __ +branch, but there is a problem keeping your package from building on __. + +Solution: make your changes in the branch and then add a digit to the +very right of the release tag. There is no need to change the release in +the other branches. This allows upgrades to work smoothly if the user +upgrades to a newer release of Fedora. + +-------------------- +Name: foo +Version: 1.0 +Release: 1%{?dist} + +Name: foo +Version: 1.0 +Release: 1%{?dist}.1 +-------------------- + +Then tag and build as usual. This approach was initially discussed +https://www.redhat.com/archives/fedora-extras-list/2006-May/msg00083.html[in +this mailing list thread]. + +[[removing-a-package-build-pending-for-rawhide-or-branched]] +=== Removing a package build pending for link:Releases/Rawhide[Rawhide] +or link:Releases/Branched[Branched] + +From time to time you may want to remove a package build you submitted +to Rawhide or to Branched prior to the Alpha freeze (both cases where +the build would usually go out to the main link:Repositories[repository] +without further gating). This could happen in a situation where a bug or +issue is found in your package that will be resolved upstream in the +next release, or you realize you made a significant mistake in the build +that cannot easily be corrected. + +You can remove the package by using Koji: + +where is replaced with the name of your package build. See or +link:Using_the_Koji_build_system[using Koji] for more information. + +[[ssh-fingerprint]] +=== ssh fingerprint + +The recommended option is to include "`VerifyHostKeyDNS yes`" in your +~/.ssh/config file. This will result in using DNS to check that the key +is correct. + +But you can also manually check against the list of keys at +https://admin.fedoraproject.org . The strings there are what ends up in +your ~/.ssh/known_hosts file. So you can accept the fingerprint when +prompted and then check that the correct string for +pkgs.fedoraproject.org ended up in your ~/.ssh/known_hosts file. + +[[problems-connecting-to-the-repository]] +=== Problems connecting to the repository + +The _fedpkg_ tool clones repositories using the ssh:// protocol, so this +should not be a problem normally (as long as you have your ssh key). If +you cloned using the _git_ utility itself, check the file to ensure the +remote repository is being accessed via an ssh:// protocol, and not +git://. + +[[expired-certificates-error-255-or-openssl.ssl.error]] +=== Expired certificates (Error 255 or OpenSSL.SSL.Error) + +This error usually means that your client certificate (~/.fedora.cert) +has expired, so you need to run fedora-cert to get a new one. If you +have trouble with this, you may try removing and re-running . + +[[it-builds-here-why-doesnt-it-build-there]] +=== It builds here, why doesn't it build there? + +Is your package building locally - even with Mock, even as a scratch +build! - but not when you run ? Before you get too frustrated, remember +runs on the package as it exists in the upstream repository, not your +local working copy. Make sure you have committed and pushed all changes +and source files, and handled the lookaside cache correctly. Other +issues that have been reported, are issues because of +https://bugzilla.redhat.com/show_bug.cgi?id=1179139[build/make check +parallelization] and failures because of test suites that depend on +operations finish on precise timing (and a busy build system may not be +able to perform operations on time). + +[[references]] +== References + +* http://pkgs.fedoraproject.org/cgit/ +* Infrastructure/Kerberos +* link:Package SCM admin requests[Package SCM admin requests] +* Package_Renaming_Process +* PackageMaintainers/PackagingTricks +* Package_update_HOWTO +* +PackageMaintainers/BuildSystemClientSetup#Install_the_Client_Tools_.28Koji.29 +* PackageMaintainers/MockTricks#How_do_I_use_Mock.3F +* Using_the_Koji_build_system +* Package_Review_Process +* Fedora_Release_Life_Cycle +* PackageMaintainers/Join +* Infrastructure/VersionControl/dist-git + +Category:Package Maintainers[Category:Package Maintainers] diff --git a/content/en-US/old/package-review-process.adoc b/content/en-US/old/package-review-process.adoc new file mode 100644 index 0000000..1bdd212 --- /dev/null +++ b/content/en-US/old/package-review-process.adoc @@ -0,0 +1,265 @@ +[[review-purpose]] += Review Purpose + +In order for a new package to be added to Fedora, the package must first +undertake a formal review. The purpose of this formal review is to try +to ensure that the package meets the quality control requirements for +Fedora. This does not mean that the package (or the software being +packaged) is perfect, but it should meet baseline minimum requirements +for quality. + +Reviews are currently done for totally new packages, +link:Package_Renaming_Process#Re-review_required[package renames], old +packages that were once deprecated returning to the collection, and +packages merged from the old Fedora Core repository. + +Note that some new packages may be exempt from the review process. +Please see Packaging:ReviewGuidelines#Package_Review_Process for a list +of criteria. If an exemption is warranted, the contributor can skip +directly to step 8 of the process: filing a +link:PackageDB_admin_requests[request] in the package database. But note +that a bugzilla ticket will still be required in order to complete that +process; please use rhbug:1376885[this bug] for this purpose and follow +the instructions there. + +[[review-process]] +== Review Process + +There are two roles in the review process, that of the contributor and +that of the reviewer. In this document, we'll present both perspectives. + +[[contributor]] +=== Contributor + +A Contributor is defined as someone who wants to submit (and maintain) a +new package in Fedora. To become a contributor, you must follow the +detailed instructions to +link:Join the package collection maintainers[Join the package collection +maintainers]. + +As a Contributor, you should have already made a package which adheres +to the Packaging:NamingGuidelines[ Package Naming Guidelines] and +Packaging:Guidelines[ Packaging Guidelines]. There are also some +packages that cannot be included in Fedora, to check if your package +applies, check if it contains any link:Forbidden items[Forbidden items]. + +When you're happy with your spec file, you should then submit that SRPM +to a package review. Currently, this is done by following these steps: + +* Put your spec file and SRPM somewhere on the Internet where it can be +directly downloaded (just HTTP(s), no registration pages or special +download methods, please). If you have no place to put your spec and +SRPM, use copr: https://copr.fedorainfracloud.org/[1]. +* Fill out a +https://bugzilla.redhat.com/bugzilla/enter_bug.cgi?product=Fedora&format=fedora-review[request +for review in bugzilla]. For guidance, a +:Image:PackageReviewProcess_review.png[screenshot of a sample bugzilla +request is available for review]. + +image:PackageReviewProcess_review.png[PackageReviewProcess_review.png,title="PackageReviewProcess_review.png"] + +* If you do not have any package already in Fedora, this means you need +a sponsor and to add FE-NEEDSPONSOR (Bugzilla id:177841) to the bugs +being blocked by your review request. For more information read the +link:How to get sponsored into the packager group[How to get sponsored +into the packager group] wiki page. +* Wait for someone to review your package! At this point in the process, +the *fedora-review* flag is blank, meaning that no reviewer is assigned. + +* There may be comments from people that are not formally reviewing the +package, they may add NotReady to the Whiteboard field, indication that +the review request is not yet ready, because of some issues they report. +After you have addressed them, please post the URLs to the updated SPEC +and SRPM file and remove it from the Whiteboard. It is expected that you +will respond to commentary, including updating your submission to +address it; if you do not, your ticket will be closed. +* A reviewer takes on the task of reviewing your package. They will set +the *fedora-review* flag to *?* +* The reviewer will review your package. You should fix any blockers +that the reviewer identifies. Once the reviewer is happy with the +package, the *fedora-review* flag will be set to *+*, indicating that +the package has passed review. +* If you have not yet been sponsored, you will not be able to progress +past this point. +* When your package pass the review, you should use the fedpkg tool to +request a git repository for it. Before doing that you will need your +https://pagure.io/fedrepo_req[pagure_api_token] configured and added +into `~/.config/rpkg/fedpkg.conf` + +`[fedpkg.pagure]` + +`token = whatever` + +For example, if your bugzilla review ticket is 12345 and you want your +package in Fedora 27, use: +`fedpkg --module-name request-repo 12345` + +* As following, if you want to add your package into more Fedora +releases, you can use the following command to request additional +branches: `fedpkg --module-name request-branch f27` +* When this is complete (tickets in Paquire for requests above are +closed as processed), you can +link:Join_the_package_collection_maintainers#Import.2C_commit.2C_and_build_your_package[import +your SRPM package] into the SCM. +* Checkout the package using `fedpkg clone ` do a final +check of spec file tags, etc. +* Request a Koji build by running `fedpkg build`. (You will need to set +up link:Infrastructure/Kerberos[Kerberos for Fedora project]) +* Repeat the process for other branches you may have requested above: +** Checkout given branch: `fedpkg switch-branch f26` +** Lets Koji build the package for this branch: `fedpkg build` +* Request updates for Fedora release branches, if necessary, using +`fedpkg update` or another Bodhi interface as detailed in Bodhi. +* If possible, add your package to +link:Upstream_release_monitoring[Upstream Release Monitoring]. +* You should make sure the review ticket is closed. You are welcome to +close it once the package has been built on the requested branches, or +if you built for one of the Fedora release branches you can ask Bodhi to +close the ticket for you when it completes the process. If you close the +ticket yourself, use *NEXTRELEASE* as the resolution. + +You do not need to go through the review process again for subsequent +package changes, and should not reference the review ticket in +subsequent updates you create in Bodhi. + +[[reviewer]] +=== Reviewer + +The Reviewer is the person who chooses to review a package. + +The Reviewer can be any Fedora account holder who is a member of the +[https://admin.fedoraproject.org/accounts/group/members/packager/* +packager group]. (If the Contributor is not yet sponsored, the review +can still proceed to completion but they will need to find a sponsor at +some point.) + +* Search for a review request that needs a reviewer: +http://fedoraproject.org/PackageReviewStatus/ (*fedora-review* flag is +blank or the bug is assigned to nobody@fedoraproject.org) +* If you notice some issues that need to be solved before you want to +start a formal review, add these issues in a comment and set the +Whiteboard of the bug to contain NotReady. This helps other possible +reviewers to notice that the review request is not yet ready for further +review action. +* if you want to formally review the package, set the *fedora-review* +flag to *?* and assign the bug to yourself. + +* Review the package ... +** Go through the MUST items listed in Packaging:ReviewGuidelines[ +Review Guidelines] . +** Go through the SHOULD items in Packaging:ReviewGuidelines[ Review +Guidelines] . +** The https://fedorahosted.org/FedoraReview/[FedoraReview] tool +(packaged as fedora-review) can help to automate this process. +* Include the text of your review in a comment in the ticket. For easy +readability, simply use a regular comment instead of an attachment. +* Take one of the following actions: +** *ACCEPT* - If the package is good, set the *fedora-review* flag to +*+* + +* ** *FAIL, LEGAL* - If the package is legally risky for whatever reason +(known patent or copyright infringement, trademark concerns) close the +bug WONTFIX and leave an appropriate comment (i.e. we don't ship mp3, so +stop submitting it). Set the *fedora-review* flag to *-*, and have the +review ticket block FE-Legal. +** *FAIL, OTHER* - If the package is just way off or unsuitable for some +other reason, and there is no simple fix, then close the bug WONTFIX and +leave an appropriate comment (i.e. we don't package pornography for +redistribution, sorry. Or, this isn't a specfile, it's a McDonald's +menu, sorry.) Set the *fedora-review* flag to *-*. +** *NEEDSWORK* - Anything that isn't explicitly failed should be left +open while the submitter and reviewer work together to fix any potential +issues. Mark the bug as NEEDINFO while waiting for the reviewer to +respond to improvement requests; this makes it easier for reviewers to +find open reviews which require their input. + +[[definitions-for-fedora-review-flag-settings]] +== Definitions for fedora-review Flag Settings + +[cols=",,",] +|======================================================================= +|fedora-review |(BLANK) |Package Needs Review + +|fedora-review |? |Package Under Review + +|fedora-review |- |Package Failed Review, dropped for legal or other +issues. + +|fedora-review |+ |Package Approved +|======================================================================= + +[[special-blocker-tickets]] +== Special blocker tickets + +There are a few tickets which can be placed in the "Blocks" field to +indicate specific ticket statuses: + +[cols=",",] +|======================================================================= +|FE-NEEDSPONSOR |The submitter requires a sponsor; the review can be +done by anyone, but a sponsor will need to come and sponsor the +submittor. + +|FE-DEADREVIEW |The review has been closed out because the submitter has +left; users looking for packages to submit may find some possibilities +in these dead tickets. + +|FE-Legal |The package is currently awaiting review by the legal team. +|======================================================================= + +[[the-whiteboard]] +== The Whiteboard + +To save time for reviewers, the page at +http://fedoraproject.org/PackageReviewStatus/NEW.html will hide certain +tickets which are not reviewable. The Whiteboard field can be used to +mark a ticket with various additional bits of status which will cause it +to be hidden or displayed differently. + +[cols=",",] +|======================================================================= +|NotReady |The package is not yet ready for review. It is possible to +open a review ticket, mark it as NotReady, and continue to work on it +until it's ready to be seen by a reviewer. + +|BuildFails |The package fails to build. + +|AwaitingSubmitter |The package review is stalled and cannot proceed +without input from the submitter. + +|Trivial |The package is trivial to review. See below. +|======================================================================= + +The "Trivial" status is intended to indicate packages which, as an aid +to new reviewers, are especially uncomplicated and easy to review. A +ticket should not be marked as being trivial unless: + +* The package is known to build and a link to a scratch build is +included. +* The ticket explains any rpmlint output which is present. +* The spec contains nothing which is unnecessary in modern Fedora (such +as BuildRoot:, a %clean section or %defattr). +* The spec is free from excessive or complicated macro usage. +* The spec uses only the least complicated scriptlets which are taken +directly from the Packaging:Scriptlets page. +* The package contains no daemons. +* The package is not especially security sensitive. +* The code has undergone a thorough inspection for licensing issues. +Anomalies which would be found by licensecheck should be explained. + +In short, this should be reserved only for those tickets which should be +easily approachable by someone doing their first package review. + +[[tracking-of-package-requests]] +== Tracking of Package Requests + +The http://fedoraproject.org/PackageReviewStatus[cached Package Review +Tracker] provides various review-related reports and a simple way to +search for reviews by package name or reporter name or others. + +[[authorship]] +== Authorship + +This document was originally authored by link:TomCallaway[Tom 'spot' +Callaway] in 2007 and has since been modified by many others. + +Category:Package Maintainers[Category:Package Maintainers] diff --git a/content/en-US/old/package-update-howto.adoc b/content/en-US/old/package-update-howto.adoc new file mode 100644 index 0000000..9493b6d --- /dev/null +++ b/content/en-US/old/package-update-howto.adoc @@ -0,0 +1,344 @@ += package update howto +This document shows how to submit an update for a package you maintain +in Fedora. It assumes you already have a package in the Fedora +repositories. It is not a guide to using the Fedora package source +control system: see the link:Package maintenance guide[Package +maintenance guide] for that. + +* For details of the policy on requirements for updates at various +stages of the link:Fedora Release Life Cycle[Fedora Release Life Cycle], +refer to link:Updates Policy[Updates Policy]. + +[[overview]] +== Overview + +This page is intended for new and existing package maintainers. Testers +and regular users may be interested in the +QA:Updates_Testing[updates-testing] repository and the +QA:Update_feedback_guidelines[update feedback guidelines]. This page +specifically covers the update submission process. + +There are two significantly different package update submission +workflows in Fedora: + +* link:Releases/Rawhide[Rawhide], and link:Releases/Branched[Branched] +up to the link:Updates Policy#Bodhi_enabling[Bodhi enabling point] +* link:Releases/Branched[Branched] releases after the Alpha change +deadline, and stable releases + +The repository layouts differ somewhat for Rawhide, Branched and stable +releases, but the update workflows split up as described above. + +[[rawhide-and-early-branched]] +== Rawhide and early Branched + +The package update workflow for Rawhide and Branched before the _Bodhi +enabling point_ is simple: + +1. Build the package with (see the +link:Package maintenance guide[Package maintenance guide] for more +details) + +This is all you need to do. Your package will appear in the next daily +compose of Rawhide or Branched and will be used in any image composes +built from that tree. + +[[later-branched-and-stable-releases]] +== Later Branched and stable releases + +At the link:Updates Policy#Bodhi_enabling[Bodhi enabling point], the +Bodhi update feedback system is enabled by +link:ReleaseEngineering[Release Engineering] and builds submitted with +are no longer automatically sent to any official +link:Repositories[repository]. The update workflow for releases of this +type is: + +1. Build the package with +2. Submit an update for the package with , the +https://admin.fedoraproject.org/updates/[Bodhi web interface], or the +https://fedorahosted.org/bodhi/wiki/CLI[Bodhi CLI tool]. This causes the +package to be sent to the +link:Repositories#updates-testing[_updates-testing_] repository +3. Monitor the update's status and the feedback you receive via the web +interface or the emails that are sent to you, and modify it with updated +or additional builds if necessary +4. After the update meets the criteria in the +link:Updates Policy[Updates Policy] and you are satisfied it should be +released as a stable update, submit the update to +_link:Repositories#stable[stable]_ with or the web interface + +[[update-attributes]] +=== Update attributes + +At the time you submit the update, you will be asked for several +attributes. The type of the update should be fairly self-explanatory: +either it fixes bugs, adds new features, or is a new package. + +If you are asked whether you want to send the update to +_updates-testing_ or _stable_, this is a no-op: all updates now go +through _updates-testing_. It does not matter what you choose. + +There are several schools of thought on filling out the update +description. Some would suggest you consider the target audience: for a +stable release, in particular, many Fedora users will see this text, and +many of them may not be particularly familiar with your package. +Consider not simply describing literally the changes in the update, but +explaining as if to an outsider why your are updating the package, what +benefits it will bring to them (if any), and anything they may want to +note in order to have a smooth update experience. + +If you associate one or more bug reports with your update, Bodhi will +post comments into Bugzilla to alert those following the bug reports +that an update is available. If you mark your update as fixing the +bug(s), Bodhi will move the report(s) through the *MODIFIED*, *ON_QA* +and *CLOSED ERRATA* states of the link:BugZappers/BugStatusWorkFlow[bug +workflow] as your update reaches various points in the process. Using +this mechanism can be very useful both for you and for users of your +package. + +You may set a _karma_ (feedback) level at which the update will +automatically be submitted to _stable_. This is optional. If you choose +to use it, please carefully consider an appropriate feedback level. For +a relatively obscure package which is quite stable, 1 or 2 may be an +appropriate value. For a popular, sensitive and complex package such as +or the , the default of 3 may be insufficient and a choice of 5 or even +10 may be appropriate. + +[[who-will-receive-your-update-when]] +=== Who will receive your update, when? + +When a release is in Branched state, the _updates-testing_ repository is +enabled by default so most users will see the package, but only packages +from the stable _fedora_ repository are used in building milestone +releases (Alpha, Beta and Final) and nightly images. + +Where a package goes when it is marked as _stable_ differs between +Branched and stable releases. In Branched releases, _stable_ packages +are pushed to the base _fedora_ repository. In stable releases, _stable_ +packages are pushed to the _updates_ repository. However, from the point +of view of the packager, this is an insignificant implementation detail. +For more details, see Repositories. + +When a release is in stable state, the _updates-testing_ repository is +disabled by default, but QA team members and others run with it enabled +in order to provide testing and Bodhi feedback. The main user population +will see your update only when it passes Bodhi, is marked as _stable_ +and reaches the _updates_ repository. + +[[updating-inter-dependent-packages]] +=== Updating inter-dependent packages + +If an update you wish to submit would cause a dependency issue of any +kind (a strict package dependency error, or simply another package +failing to operate correctly) if updated alone, you must not submit the +package as a single-package update. You must always collect all +inter-dependent or related packages together into a single multi-package +update, such that no user will face problems if they install all the +packages in the update together. + +For example: if you maintain a package _libfoo_ which the package _bar_ +depends on, and you need to update _libfoo_, you should check that _bar_ +continues to function correctly with the updated version of _libfoo_. If +it does not, you must ensure the appropriate changes are made to _bar_, +and include the updated _bar_ in your update along with the updated +_libfoo_. + +The _fedpkg_ tool does not handle multi-package updates. You can add +multiple packages to an update using the +https://admin.fedoraproject.org/updates/[Bodhi web application], or the +command line tool. You can pass as many package names as you like to the +to create a new multi-package update, or use to edit an existing update. + +It is possible you will run into problems with permissions when trying +to add builds of packages you do not have commit privileges for to an +update, or trying to add a build for a package you do have privileges +for to someone else's update. If you encounter a situation like this, +you should contact the link:ReleaseEngineering[release engineering] team +or a proven packager for help. + +You may need a _buildroot override_ to complete a multi-package update +successfully. For instance in the case described above, you may need to +rebuild _bar_ against the new _libfoo_ package and submit both packages +together as a multi-package update. However, in the normal course of +events, you would not be able to build another package against your new +_libfoo_ build until it reached the link:Repositories#stable[_stable_] +state. To resolve this dilemma, you can request a buildroot override, +which causes the _libfoo_ build to be included in the buildroot for a +short time in order to get the _bar_ package build done. + +You can request a buildroot override with bodhi: This would submit a +buildroot override with a duration of two days. Buildroot overrides are +usually granted within 15-30 minutes of submission. If you submit an +override request with the bodhi tool, it will suggest a command that +will let you monitor when the package appears in the buildroot, so you +can fire your dependent build at the appropriate time. + +You can also request buildroot overrides from the +https://admin.fedoraproject.org/updates/[Bodhi web application]. + +The link:Bodhi/BuildRootOverrides[buildroot override instructions] +explain the buildroot override process in more detail. + +[[handling-feedback-from-automated-tests]] +=== Handling feedback from automated tests + +Fedora's automated testing systems, Taskotron and OpenQA, may run +automated tests on your update. Several of the Taskotron/Tasks are +documented. The openQA tests are functional tests of some critical +Workstation and Server features. + +In the Bodhi web interface, updates have a _Automated Tests_ tab which +displays the results of all automated tests. Tests shown with a red +background failed. The tests are not all 100% accurate, but they are +fairly often correct. If you see a failure, it is a very good idea to +click on the result (which will take you to a detailed log) and +investigate the issue. If you are unsure what the test indicates, you +can contact the QA team for help. + +[[waive-a-result]] +==== Waive a result + +At present, a failure of the _dist.rpmdeplint_, _dist.abicheck_, or +_org.centos.prod.ci.pipeline.complete_ tests will prevent your update +from being released. On the update's _Details_ page in the Bodhi web +interface, the *Test Gating Status* will be shown as _N of N required +tests failed_. If you are sure such a failure is a false one, you can +'waive' the result using the tool, from the package (there is +https://github.com/fedora-infra/bodhi/pull/2095[work pending] to be able +to waiver more easily, directly from the Bodhi UI). + +You can submit a waiver for a failing result with specifying the and the +: + +  waiverdb-cli -t YOUR_TESTCASE_HERE \ + -s '{"item": "this-is-the-subject", "type": "also-this-is-part-of-the-subject"}' + -p "fedora-26" -c "This is fine" + +Example: + +  waiverdb-cli -t dist.rpmdeplint \ + -s '{"item": "python-requests-1.2.3-1.fc26", "type": "koji_build"}'  + -p "fedora-26" -c "This is fine" + +You can also waive a failing result by result's id, which you can +retrieve from resultsdb with curl. To do that, you'll need the name and +the . For example: + + curl "https://taskotron.fedoraproject.org/resultsdb_api/api/v2.0/results?testcases=dist.python-versions&item=python-alembic-0.9.7-1.fc27" | jq ".data[0].id" + +This should print out the of the failing result. You can then submit a +waiver for this failing result with + + waiverdb-cli -p fedora-27 -r YOUR_ID_HERE -c "This is fine." + +Also, if you enabled automatic stable push at a karma threshold, this +will be disabled if any automated test fails. If you have examined the +result and you are sure it is a false one and there is no problem with +the package, you may re-enable the automatic push mechanism or submit +the package to _stable_ manually once it meets the other requirements of +the link:Updates Policy[Updates Policy]. + +[[waive-the-absence-of-a-result]] +==== Waive the absence of a result + +Submitting a waiver using subject/testcase allows to waive the absence +of a result (eg. the test never ran for some reason, so there is no +result item). + +If which testcase you should be specified it is not clear/known, it is +possible to run this python script, chainging it with the corrects +parameter: + + #!/usr/bin/env python + """ Ask a question of greenwave.  """ + # Usage: either modify and set PRODUCT_VERSION and NVR_LIST and run,  + # or pass version as first arg and then NVRs as further args + import pprint + import requests + import sys + PRODUCT_VERSION = 'fedora-27' if len(sys.argv) == 1 else sys.argv[1] + NVR_LIST = [] or sys.argv[2:]  # Insert your NVRs here, or pass them via command line args + for nvr in NVR_LIST: +     url = ( +         'https://greenwave-web-greenwave.app.os.fedoraproject.org/' +         'api/v1.0/decision') +     payload = dict( +         #verbose=True, +         decision_context='bodhi_update_push_stable', +         product_version=PRODUCT_VERSION, +        subject=[{'item': nvr, 'type': 'koji_build'}], +     ) +     response = requests.post(url, json=payload) +     print("-" * 40) +     print(nvr, response, response.status_code) +     data = response.json() +     print(pprint.pformat(data)) + +The output will show that Greenwave is requiring a specific testcase to +run, but it cannot find a result for it (neither pass nor failure). So +now it is possible to submit a waiver with the specified testcase in the +output and the subject already known. + +[[troubleshooting]] +==== Troubleshooting + +If you run the tool and it gives you the following error: + +  Error: The config option "resultsdb_api_url" is required + +Edit and add the following line: + +  resultsdb_api_url=`https://taskotron.fedoraproject.org/resultsdb_api/api/v2.0 + +[[branched-milestone-freezes]] +=== Branched milestone freezes + +For a short period before each milestone release, the stable +link:Repositories#fedora[_fedora_] repository is frozen. These periods +are shown as the link:Milestone freezes[Milestone freezes] (Beta Freeze, +Final Freeze) on schedules. During these periods, builds will not be +marked _stable_ and pushed from +link:Repositories#updates-testing[_updates-testing_] to _fedora_ even +after being submitted manually or automatically. In the normal course of +events, they will be pushed after the milestone release is approved at a +Go_No_Go_Meeting. If you believe your update deserves to break a +milestone freeze, a _freeze exception_ may be granted through the +QA:SOP_freeze_exception_bug_process[freeze exception process]. Accepted +release blocking bugs are granted the same status through the +QA:SOP_blocker_bug_process[blocker bug process]. + +For more on the Fedora development process, see +link:Fedora Release Life Cycle[Fedora Release Life Cycle]. + +[[security-updates]] +== Security updates + +There is an additional process that layers over the regular update +process for bugs identified as security issues. If a bug is assigned to +you that blocks a link:Security Tracking Bugs[security tracking bug], +you must follow that process in addition to this one. + +[[new-package-submissions]] +== New package submissions + +If you want to build a new package, but you aren't sure which releases +to send it to: + +* New packages should always be built for Rawhide +* New packages can be built for Branched and stable releases if adding +them would provide value to users of those releases without significant +risk of causing harm + +The submission process for new packages, after they have passed the +Package_Review_Process and been link:Package_SCM_admin_requests[given an +SCM repository], is exactly the same as that for package updates. + +[[consider-creating-a-package-test-plan]] +== Consider creating a package test plan + +If you QA:SOP_test_case_creation[create test cases] for your package, +and QA:SOP_package_test_plan_creation[categorize them appropriately], +they will be automatically linked in Bodhi, so that testers will have +some guidance for planned update testing. + +Category:Package Maintainers[Category:Package Maintainers] diff --git a/content/en-US/old/what-happened-to-pkgdb.adoc b/content/en-US/old/what-happened-to-pkgdb.adoc new file mode 100644 index 0000000..cfc0251 --- /dev/null +++ b/content/en-US/old/what-happened-to-pkgdb.adoc @@ -0,0 +1,317 @@ +[[why-pkgdb-is-being-decommissioned]] += Why PkgDB Is Being Decommissioned + +In general, PkgDB works well for the current workflow of a package’s +lifecycle. Currently, a package has several branches that are tied to +Fedora releases such as “f24” or “f25”. These branches have implied +service levels (SLs) and end of life (EOL) dates based on the Fedora +release itself. Although the implied SLs and EOLs in these branches have +worked well for Fedora in the past, it’s becoming increasingly difficult +to juggle different application lifecycles and their dependencies’ +lifecycles under the umbrella of these limited number of SLs and EOLs, +especially when trying to keep up with upstream. In the past, we have +not been able to have different package lifecycles within a Fedora +release due to the nature of its design. With +https://docs.pagure.org/modularity/[Modularity], that will become a +reality, and Fedora packagers and module maintainers will need a new way +of branching in dist-git to enable this functionality. + +Since PkgDB was written with the old way of branching in mind, there +ended up being two logical paths forward. We could significantly rewrite +PkgDB to work with the new branching methodology, or we could migrate +PkgDB's existing functionality to other tooling. After talking with some +folks in the Fedora community, the latter seemed to be the right +approach because Fedora was moving to "Pagure over Dist-Git", and that +was going to duplicate and clash with a lot of PkgDB's functionality +anyways. + +[[how-is-pkgdbs-functionality-being-replaced]] +== How Is PkgDB's Functionality Being Replaced? + +PkgDB has two primary functions. It provides package repo ACLs, and +package related "admin requests" and "admin actions". After PkgDB will +be replaced, ACLs will be handled in +https://src.fedoraproject.org/[Pagure over Dist-Git (placeholder link)] +at the package level like you would handle a traditional code repository +on https://pagure.io/[pagure.io]. As for "admin requests" and "admin +actions", those will be replaced by a CLI tool called +https://pagure.io/fedrepo_req[fedrepo-req] (see: +https://fedorapeople.org/groups/factory2/sprint-032/mprahl-fedrepo-req-admin.mp4[a +demo]) that will submit JSON formatted tickets on your behalf to a +ticket queue in a specific Pagure project monitored by the Fedora +Release Engineering group. + +For more information on this or information on how other features in +PkgDB are being replaced, please read the "How To Make This Change" +section of the +https://fedoraproject.org/wiki/Infrastructure/Factory2/Focus/ArbitraryBranching[Arbitrary +Branching Focus Document] written by the Factory 2.0 team. + +[[helpfaqs]] +== Help/FAQs + +[[how-do-i-give-a-user-commit-access-to-a-dist-git-repo]] +=== How do I give a user commit access to a dist-git repo? + +1. Browse to your project on https://src.fedoraproject.org/[Pagure over +Dist-Git (Top Level link)] +2. Click 'browse' in the top right, to open a search box +3. Enter the package name and select the proper package from the +results +4. Click on "Settings" +5. Scroll down to "Users and Groups" +6. Click on "add user" +7. Type the username in the form +8. Select "commit" instead of the default of "ticket" to set the level +of access +9. Click "Add" + +[[how-do-i-request-commit-access-to-a-dist-git-repo]] +=== How do I request commit access to a dist-git repo? + +Email the PACKAGENAME-owner@fedoraproject.org alias asking to be given +access, or file a bugzilla bug on the package asking for access. + +[[how-do-i-request-a-new-package-or-a-new-branch]] +=== How do I request a new package or a new branch + +The ticketing functionality of PkgDB was replaced by a set of command +line tools called https://pagure.io/fedrepo_req[fedrepo-req], which are +packaged in Fedora and EPEL as +https://apps.fedoraproject.org/packages/fedrepo-req[`fedrepo-req`]. The +`fedrepo-req` command requests the creation of repositories for new +packages, and the `fedrepo-req-branch` command requests new branches for +existing packages. Please review the manual pages for information on +using these tools. + +Please note that new branch requests, when processed, will only cause +the creation of an entry in the PDC. You must then create the branch in +git manually. + +[[how-do-i-orphan-a-package]] +=== How do I orphan a package? + +Visit the package's repo in pagure and navigate to the settings for that +repo. I.e. + +https://src.fedoraproject.org/rpms/PACKAGE_NAME/settings + +Navigate down to the _Give Project_ section and "give" the project to +the "orphan" user. + +For completeness, under the _Users and Groups_ section, remove yourself +from the list. + +[[how-do-i-retire-a-package]] +=== How do I retire a package? + +Run _fedpkg retire_ in a local git checkout of the package's repo. + +[[how-can-i-watch-a-packages-commits]] +=== How can I watch a package's commits? + +Navigate to the project's repo: + +https://src.fedoraproject.org/rpms/PACKAGE_NAME + +* There should be a little icon with an eyeball in the top right. +* Click it. +* There should be a drop-down with various options for different kinds +of "watch" activity. +* The one you want should say "watch commits". + +[[how-can-i-get-added-to-the-cc-list-of-a-package-bug-reports]] +=== How can I get added to the CC list of a package bug reports? + +This used to be called "watchbugs" in pkgdb. Similar to "watchcommits", +which is addressed in the question above this one... + +Navigate to the project's repo: + +https://src.fedoraproject.org/rpms/PACKAGE_NAME + +* There should be a little icon with an eyeball in the top right. +* Click it. +* There should be a drop-down with various options for different kinds +of "watch" activity. +* The one you want is "watch issues and PRs". + +[[how-do-i-become-the-default-assignee-of-a-branch-in-bugzilla]] +=== How do I become the default assignee of a branch in bugzilla? + +File a pull-request on the +https://pagure.io/releng/fedora-scm-requests/blob/master/f/rpms[releng/fedora-scm-requests] +repo to add your FAS username. + +[[how-do-i-change-the-upstream-monitoringanitya-flag-for-my-packages]] +=== How do I change the upstream-monitoring/anitya flag for my packages? + +File a pull-request on the +https://pagure.io/releng/fedora-scm-requests/blob/master/f/rpms[releng/fedora-scm-requests] +repo to tweak the ``monitoring`` setting for your packages. + +[[how-do-i-transfer-ownership-of-a-package-to-someone-else]] +=== How do I transfer ownership of a package to someone else? + +Navigate to the project's repo's *settings* page: + +https://src.fedoraproject.org/rpms/PACKAGE_NAME/settings + +Scroll down to the "give project" section. There you can give the +package to someone else. + +[[how-do-i-adopt-an-orphaned-package-or-unretire-a-package]] +=== How do I adopt an orphaned package or unretire a package? + +For now, file a https://pagure.io/releng/issues[release engineering +ticket] with the name of the package, what you need done and in the case +of unretirement, the re-review of the package (if required). + +In the case of adopting an orphaned package, they should be able to give +it to you with the +https://pagure.io/releng/blob/master/f/scripts/distgit/give-package.py[give-package.py] +script. + +In the case of unretiring a package, they should follow the +https://docs.pagure.org/releng/sop_unretire.html[SOP for unretiring a +package]. + +[[how-do-i-find-out-who-owns-a-package]] +=== How do I find out who owns a package? + +1. Browse to the project on https://src.fedoraproject.org/[Pagure over +Dist-Git (placeholder link)] you are interested in +2. On the right side of the page, there is a heading called +"Contributors". Under that heading, there will be a username with "(main +admin)" displayed next to it. That is the owner of the package. + +[[how-do-i-find-out-the-list-of-orphaned-packages]] +=== How do I find out the list of orphaned packages? + +All orphaned packages will be owned by the "orphan" FAS user account in +https://src.fedoraproject.org/[Pagure over Dist-Git (placeholder link)]. + +You may use the user interface to view all the projects owned by the +"orphan" user, but this will include repos other than just packages +(like containers or modules): +https://src.fedoraproject.org/user/orphan[https://src.fedoraproject.org/user/orphan +(placeholder link)] + +You may use the REST API to view only the orphaned RPM repos by +visiting: +https://src.fedoraproject.org/api/0/projects?namespace=rpms&owner=orphan[https://src.fedoraproject.org/api/0/projects?namespace=rpms&owner=orphan +(placeholder link)] + +[[how-do-i-find-the-list-of-retired-packagesbranches-incomplete]] +=== How do I find the list of retired packages/branches? (incomplete) + +Retired branches are tracked in PDC by setting the "active" flag to +"false" on a branch. + +To view all packages with a master branch that is retired, you can visit +the following: +https://pdc.fedoraproject.org/rest_api/v1/component-branches/?active=false&type=rpms&name=master[https://pdc.fedoraproject.org/rest_api/v1/component-branches/?active=false&type=rpms&name=master] + +To view all retired package branches, you can visit the following: +https://pdc.fedoraproject.org/rest_api/v1/component-branches/?active=false&type=rpms[https://pdc.fedoraproject.org/rest_api/v1/component-branches/?active=false&type=rpms] + +To view all retired packages, a script will need to be written to query +PDC and perform a process of elimination. + +[[how-do-i-find-a-branchs-sls]] +=== How do I find a branch's SLs? + +A branch's SLs (termed SLA in PDC) are stored in the Product Definition +Center (PDC). An entry in PDC is required for a package to be used in a +module. As an example, if you wanted to view the Python package's SLs +for the 2.7 branch, you can visit the link below. You'll notice that the +URL contains three parameters to the request. The "type" is set to +"rpms", which filters the request down to just RPM packages. The +"global_component" is set to "python", which filters it down to only +branches belonging to any "python" component (e.g. an RPM, container, +module, etc). Lastly, the "name" is set to "2.7, which filters it down +to only "2.7" branches of components. All these filters together give +you a unique result of the Python 2.7 RPM branch. +https://pdc.fedoraproject.org/rest_api/v1/component-branches/?type=rpms&global_component=python&name=2.7[https://pdc.fedoraproject.org/rest_api/v1/component-branches/?type=rpms&global_component=python&name=2.7] + +[[how-do-i-find-what-sls-are-available-for-use]] +=== How do I find what SLs are available for use? + +All available SLs are defined in the Product Definition Center (PDC) at: +https://pdc.fedoraproject.org/rest_api/v1/component-branch-slas/[https://pdc.fedoraproject.org/rest_api/v1/component-branch-slas/] + +[[how-do-i-set-an-sl-on-my-branch]] +=== How do I set an SL on my branch? + +The SL of your branch is set when you request your branch. For more +information on requesting a branch, please review the +https://fedoraproject.org/w/index.php?title=Infrastructure/WhatHappenedToPkgdb#How_do_I_request_a_new_package.2C_a_new_branch.2C_or_to_unretire_a_package.3F[How +do I request a new package, a new branch, or to unretire a package?] +section of this FAQ. + +[[will-there-be-an-f27-branch]] +=== Will there be an "f27" branch? + +Yes, we will automatically create an "f27" branch that will in general +act like the "f26" branch but with explicit SLs that match what we would +expect from the implicit SLs of a traditional Fedora 27 release. This +means packagers don't have to change their branching strategy if they +don't want to. For f28, we intend to propose to FESCo that we do not +create global "f28" branches for all packages. + +(If one branch is suitable for multiple Fedora releases, it may be less +work for the packager to create a single branch that is used by all +those releases instead of maintaining a branch per release. To arrive at +this scenario, at some point we have to stop automatically creating new +branches for new distro releases.) + +[[in-what-circumstances-should-i-request-a-new-style-branch]] +=== In what circumstances should I request a new-style branch? + +For context, go back to review Changes/ArbitraryBranching. Traditional +Fedora dist-git branches are _named in correspondence with a release of +the distro_. "New-style" branches allow packagers to name a branch +"arbitrarily". See advice on choose a name in the next subsection. + +There could be many reasons to request a new-style branch. The primary +reason is if you'd like a branch that doesn't have an SL of a +traditional Fedora release. If for instance, you create a branch that +can serve multiple Fedora releases, that would end up being less work +for you as the packager since you only maintain one branch instead of +many with the same code base. Another instance is if your package needs +to have breaking changes that are frequent and violate the lifecycle of +a traditional Fedora release. The latter example could not, however, be +included in a Fedora release since it's SL is lower than the SL of a +release. + +[[how-should-i-name-my-branch]] +=== How should I name my branch? + +At this time, there are no restrictions on how you name your branches +except that they may not be derogatory or offensive; they may not +violate the https://getfedora.org/code-of-conduct[Fedora Community Code +of Conduct]. + +Try to use branch names that best describe the SL you are trying to +provide. For instance, if you maintain a package that is at version 2.7 +for a while, you could create a branch called "2.7" which would be +updated with every 2.7.x release upstream. Another example is if you are +always trying to package the latest upstream version, you could call +your branch "latest". It's really up to you, but just try to be +informative and considerate when choosing names. + +Requests for new branches will still pass through a member of the +'cvsadmin' group for approval. They may adopt more specific policy over +time. + +[[how-do-i-pick-an-sl-for-my-branch]] +=== How do I pick an SL for my branch? + +See https://fedoraproject.org/wiki/Module:Guidelines#SLs_and_EOLs[this +section] of the Module guidelines for information on selecting the +appropriate SLs. + +[[how-do-i-find-the-list-of-modules-that-pull-in-my-branch]] +=== How do I find the list of modules that pull in my branch? + +Try https://pagure.io/releng/pull-request/6970[this script]. diff --git a/content/en-US/package-maintenance-guide.adoc b/content/en-US/package-maintenance-guide.adoc deleted file mode 100644 index a2f49bd..0000000 --- a/content/en-US/package-maintenance-guide.adoc +++ /dev/null @@ -1,369 +0,0 @@ -= package maintainence guide -This page provides some basic instructions for day-to-day usage of the -http://git-scm.com/[git]-based package maintenance system for Fedora. It -is intended primarily for new and current Fedora package maintainers, -but does briefly link:#anon[cover anonymous read-only use of the -system]. It is not a guide to RPM packaging per se. Some pre-existing -knowledge of git may be useful, but is not a pre-requisite (in fact, -Fedora packaging can be a relatively painless introduction to it). - -You may have been looking for, or also be interested in: - -* link:How_to_create_an_RPM_package[Learning to create packages] -* link:Join_the_package_collection_maintainers[Becoming a package -maintainer] -* link:Package_update_HOWTO[Submitting package updates] -* link:New_package_process_for_existing_contributors[Adding a new -package to the repository] as an existing maintainer -* -link:PackageDB_admin_requests#Additional_branches_for_existing_packages[adding -a new release branch] to an existing package -* Packaging:Guidelines[The Packaging Guidelines] - -[[installing-fedpkg-and-doing-initial-setup]] -== Installing _fedpkg_ and doing initial setup - -Start by installing with . This will also install the tool, which will -be your primary interface to the packaging system. Run to configure your -machine for package maintenance. If you have run before, but wish to set -up a new machine, copy the files to the new system. - -You also must have an ssh key configured in the -https://admin.fedoraproject.org/accounts/[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) - -[[common-fedpkg-commands]] -== Common fedpkg commands - -This section lists typical fedpkg commands in a normal workflow, with -short descriptions. Longer explanations for each can be seen by clicking -the 'Show' links. In this workflow, we will be operating on the -link:Releases/Rawhide[Rawhide] branch of the package. - -* Check out a package: - -`fedpkg co ` + -`cd ` - -* Update your checked-out copy from the Fedora server: - -`fedpkg pull` - -* Retrieve the package sources: - -`fedpkg sources` - -* Make your changes to the package - -* Run the 'prep' stage (extract source, apply patches etc) within the -checkout directory: - -`fedpkg prep` - -* Do a local build of the current state: - -`fedpkg local` - -* Do a mock build of the current state: - -`fedpkg mockbuild` - -* Generate a .src.rpm from the current state: - -`fedpkg srpm` - -* Do a scratch build using koji: see -https://fedoraproject.org/wiki/Using_the_Koji_build_system#Scratch_Builds[Koji -scratch builds] -* Check changes you have made: - -`fedpkg diff` - -* Run some checks (rpmlint) on your package: - -`fedpkg lint` - -* Stage any small patches or new source files for commit: - -`git add (somefile)` - -* Upload new source files to the lookaside cache: - -`fedpkg new-sources` - -`fedpkg upload` - -* Switch to a different release branch: - -`fedpkg switch-branch ` - -* Generate git changelog from package changelog: - -`fedpkg clog` - -* Commit changes: - -`fedpkg commit (-F clog) (-p) (-c)` - -* Push changes: - -`fedpkg push` - -* Do an 'official' build of the latest pushed changes: - -`fedpkg build` - -* In the event you are working with a Docker -link:Changes/Layered_Docker_Image_Build_Service[Container Layered Image -Build] - -`fedpkg container-build` - -* Submit a package update for the latest build: - -`fedpkg update` - -[[typical-fedpkg-session]] -== Typical _fedpkg_ session - -A typical session may look like this: - ---------------------------------------------------------------------------- -fedpkg clone foo -cd foo -fedpkg sources -fedpkg new-sources foo-0.0.2.tar.bz2 -gedit foo.spec # change the required things in the specfile. - # rpmdev-bumpspec is useful for simple version updates -fedpkg mockbuild # check that the changes you made are correct -fedpkg diff -fedpkg lint -fedpkg commit -p -c # commit and push in one go ---------------------------------------------------------------------------- - -[[working-with-branches]] -== Working with branches - -Each Fedora release is represented by a branch in the git repository. -You can switch between them like this: - -`fedpkg switch-branch f` + -`fedpkg switch-branch f` + -`fedpkg switch-branch master` - -The _master_ branch is for link:Releases/Rawhide[Rawhide]. You can -maintain each branch entirely separately, if you like, laboriously -copying changes between them (so long as you always stay within the -link:Updates Policy[Updates Policy] requirements). However, git provides -us with several handy tools for working with branches. Here's an -example: This will 'merge' the changes from the _master_ (Rawhide) -branch to the f branch. git aficionados may note this is a somewhat -unusual workflow, but it is appropriate to the context of package -management. Remember, after pushing to and building for a stable release -or a link:Releases/Branched[Branched] release after -link:Updates Policy#Bodhi_enabling[Bodhi has been enabled], you will -have to link:Package_update_HOWTO[submit an update] before any other -Fedora users will see your build. - -Note that merges will only be sure to work cleanly so long as the -branches have not previously diverged. That is, if you do this: you may -encounter a _merge conflict_. - -Remember that git is a _collaborative_ system, and used as such in -Fedora package management. It is often the case that you must consider -changes made by others in working on a package, and consider how your -changes will affect others. - -[[resolving-merge-conflicts]] -=== Resolving merge conflicts - -This is a large topic and somewhat beyond the scope of this guide, but -we can give basic pointers. There are other good references in the -http://git-scm.com/book/en/Git-Branching-Basic-Branching-and-Merging[git -book] and at -https://help.github.com/articles/resolving-a-merge-conflict-from-the-command-line[github]. - -When you git merge and a conflict occurs you can edit the files that -have conflicts. Remove the conflict markers in the files and merge the -changes manually. Use or to inspect the changes against the pre-conflict -state and verify you are happy with the resolution. Then you can commit -the files with or . git will know if you have resolved the conflict by -checking that all the conflict markers have been removed. - -[[using-git-mergetool-to-resolve-conflicts]] -=== Using `git mergetool` to resolve conflicts - -Git provides a graphical diff program to help resolve conflicts. This -can be handy for visualizing what changes have occurred and dealing with -them as a set. - -[[requesting-special-dist-tags]] -== Requesting special dist tags - -When a change to a package affects a large number of dependencies (e.g. -all perl, python, ruby or ghc packages), requiring them to be rebuilt, -it may be better to initially do the builds in a special repository, so -that there is less disruption in Rawhide. - -If you think you have an update that falls under this case you can -request a special dist tag by filing a -https://fedorahosted.org/rel-eng/newticket[release engineering ticket]. -Someone from link:ReleaseEngineering[release engineering] will likely -want to discuss your needs to make sure this is really an appropriate -case (it's OK ask if you aren't sure) and that you get what you need. - -[[tips-and-tricks]] -== Tips and tricks - -[[using-fedpkg-anonymously]] -=== Using fedpkg anonymously - -You can use fedpkg like this: - -`fedpkg clone --anonymous ` - -to check out a package without requiring identification. Obviously, you -will not be able to push any changes to this repository, but it is -useful for non-packagers who simply want to examine a package, make -changes for their own use, and perhaps submit changes to a Fedora -developer. - -[[local-branch-names]] -=== Local branch names - -If you use git commands to branch and checkout directly, you can define -whatever local branch names you want. If you use , it will default to -creating the names used in the examples above. - -[[current-branch-and-state-in-shell-prompt]] -=== Current branch and state in shell prompt - -It is often helpful to know what branch you are working on at a glance. -You can add this information to your bash prompt with the information -link:Git_Quickref#Display_current_branch_in_bash[here]. - -[[importing-a-.src.rpm-to-update]] -=== Importing a .src.rpm to update - -The command usually used to initially populate a git package repository -from a .src.rpm that has been through the -link:Package Review Process[Package Review Process] can also be used to -update a normal working copy, if you have an old-school packaging -process to which you are particularly attached. Just run and it will -upload new tarballs into lookaside cache, update a working copy of the -last version found in git, and commit all changes. documents some other -parameters it can accept. - -[[making-changes-on-an-older-branch-without-breaking-the-upgrade-path]] -=== Making changes on an older branch without breaking the upgrade path - -Here is the scenario: you've built your package successfully on the __ -branch, but there is a problem keeping your package from building on __. - -Solution: make your changes in the branch and then add a digit to the -very right of the release tag. There is no need to change the release in -the other branches. This allows upgrades to work smoothly if the user -upgrades to a newer release of Fedora. - --------------------- -Name: foo -Version: 1.0 -Release: 1%{?dist} - -Name: foo -Version: 1.0 -Release: 1%{?dist}.1 --------------------- - -Then tag and build as usual. This approach was initially discussed -https://www.redhat.com/archives/fedora-extras-list/2006-May/msg00083.html[in -this mailing list thread]. - -[[removing-a-package-build-pending-for-rawhide-or-branched]] -=== Removing a package build pending for link:Releases/Rawhide[Rawhide] -or link:Releases/Branched[Branched] - -From time to time you may want to remove a package build you submitted -to Rawhide or to Branched prior to the Alpha freeze (both cases where -the build would usually go out to the main link:Repositories[repository] -without further gating). This could happen in a situation where a bug or -issue is found in your package that will be resolved upstream in the -next release, or you realize you made a significant mistake in the build -that cannot easily be corrected. - -You can remove the package by using Koji: - -where is replaced with the name of your package build. See or -link:Using_the_Koji_build_system[using Koji] for more information. - -[[ssh-fingerprint]] -=== ssh fingerprint - -The recommended option is to include "`VerifyHostKeyDNS yes`" in your -~/.ssh/config file. This will result in using DNS to check that the key -is correct. - -But you can also manually check against the list of keys at -https://admin.fedoraproject.org . The strings there are what ends up in -your ~/.ssh/known_hosts file. So you can accept the fingerprint when -prompted and then check that the correct string for -pkgs.fedoraproject.org ended up in your ~/.ssh/known_hosts file. - -[[problems-connecting-to-the-repository]] -=== Problems connecting to the repository - -The _fedpkg_ tool clones repositories using the ssh:// protocol, so this -should not be a problem normally (as long as you have your ssh key). If -you cloned using the _git_ utility itself, check the file to ensure the -remote repository is being accessed via an ssh:// protocol, and not -git://. - -[[expired-certificates-error-255-or-openssl.ssl.error]] -=== Expired certificates (Error 255 or OpenSSL.SSL.Error) - -This error usually means that your client certificate (~/.fedora.cert) -has expired, so you need to run fedora-cert to get a new one. If you -have trouble with this, you may try removing and re-running . - -[[it-builds-here-why-doesnt-it-build-there]] -=== It builds here, why doesn't it build there? - -Is your package building locally - even with Mock, even as a scratch -build! - but not when you run ? Before you get too frustrated, remember -runs on the package as it exists in the upstream repository, not your -local working copy. Make sure you have committed and pushed all changes -and source files, and handled the lookaside cache correctly. Other -issues that have been reported, are issues because of -https://bugzilla.redhat.com/show_bug.cgi?id=1179139[build/make check -parallelization] and failures because of test suites that depend on -operations finish on precise timing (and a busy build system may not be -able to perform operations on time). - -[[references]] -== References - -* http://pkgs.fedoraproject.org/cgit/ -* Infrastructure/Kerberos -* link:Package SCM admin requests[Package SCM admin requests] -* Package_Renaming_Process -* PackageMaintainers/PackagingTricks -* Package_update_HOWTO -* -PackageMaintainers/BuildSystemClientSetup#Install_the_Client_Tools_.28Koji.29 -* PackageMaintainers/MockTricks#How_do_I_use_Mock.3F -* Using_the_Koji_build_system -* Package_Review_Process -* Fedora_Release_Life_Cycle -* PackageMaintainers/Join -* Infrastructure/VersionControl/dist-git - -Category:Package Maintainers[Category:Package Maintainers] diff --git a/content/en-US/package-review-process.adoc b/content/en-US/package-review-process.adoc deleted file mode 100644 index 1bdd212..0000000 --- a/content/en-US/package-review-process.adoc +++ /dev/null @@ -1,265 +0,0 @@ -[[review-purpose]] -= Review Purpose - -In order for a new package to be added to Fedora, the package must first -undertake a formal review. The purpose of this formal review is to try -to ensure that the package meets the quality control requirements for -Fedora. This does not mean that the package (or the software being -packaged) is perfect, but it should meet baseline minimum requirements -for quality. - -Reviews are currently done for totally new packages, -link:Package_Renaming_Process#Re-review_required[package renames], old -packages that were once deprecated returning to the collection, and -packages merged from the old Fedora Core repository. - -Note that some new packages may be exempt from the review process. -Please see Packaging:ReviewGuidelines#Package_Review_Process for a list -of criteria. If an exemption is warranted, the contributor can skip -directly to step 8 of the process: filing a -link:PackageDB_admin_requests[request] in the package database. But note -that a bugzilla ticket will still be required in order to complete that -process; please use rhbug:1376885[this bug] for this purpose and follow -the instructions there. - -[[review-process]] -== Review Process - -There are two roles in the review process, that of the contributor and -that of the reviewer. In this document, we'll present both perspectives. - -[[contributor]] -=== Contributor - -A Contributor is defined as someone who wants to submit (and maintain) a -new package in Fedora. To become a contributor, you must follow the -detailed instructions to -link:Join the package collection maintainers[Join the package collection -maintainers]. - -As a Contributor, you should have already made a package which adheres -to the Packaging:NamingGuidelines[ Package Naming Guidelines] and -Packaging:Guidelines[ Packaging Guidelines]. There are also some -packages that cannot be included in Fedora, to check if your package -applies, check if it contains any link:Forbidden items[Forbidden items]. - -When you're happy with your spec file, you should then submit that SRPM -to a package review. Currently, this is done by following these steps: - -* Put your spec file and SRPM somewhere on the Internet where it can be -directly downloaded (just HTTP(s), no registration pages or special -download methods, please). If you have no place to put your spec and -SRPM, use copr: https://copr.fedorainfracloud.org/[1]. -* Fill out a -https://bugzilla.redhat.com/bugzilla/enter_bug.cgi?product=Fedora&format=fedora-review[request -for review in bugzilla]. For guidance, a -:Image:PackageReviewProcess_review.png[screenshot of a sample bugzilla -request is available for review]. - -image:PackageReviewProcess_review.png[PackageReviewProcess_review.png,title="PackageReviewProcess_review.png"] - -* If you do not have any package already in Fedora, this means you need -a sponsor and to add FE-NEEDSPONSOR (Bugzilla id:177841) to the bugs -being blocked by your review request. For more information read the -link:How to get sponsored into the packager group[How to get sponsored -into the packager group] wiki page. -* Wait for someone to review your package! At this point in the process, -the *fedora-review* flag is blank, meaning that no reviewer is assigned. - -* There may be comments from people that are not formally reviewing the -package, they may add NotReady to the Whiteboard field, indication that -the review request is not yet ready, because of some issues they report. -After you have addressed them, please post the URLs to the updated SPEC -and SRPM file and remove it from the Whiteboard. It is expected that you -will respond to commentary, including updating your submission to -address it; if you do not, your ticket will be closed. -* A reviewer takes on the task of reviewing your package. They will set -the *fedora-review* flag to *?* -* The reviewer will review your package. You should fix any blockers -that the reviewer identifies. Once the reviewer is happy with the -package, the *fedora-review* flag will be set to *+*, indicating that -the package has passed review. -* If you have not yet been sponsored, you will not be able to progress -past this point. -* When your package pass the review, you should use the fedpkg tool to -request a git repository for it. Before doing that you will need your -https://pagure.io/fedrepo_req[pagure_api_token] configured and added -into `~/.config/rpkg/fedpkg.conf` - -`[fedpkg.pagure]` + -`token = whatever` - -For example, if your bugzilla review ticket is 12345 and you want your -package in Fedora 27, use: -`fedpkg --module-name request-repo 12345` - -* As following, if you want to add your package into more Fedora -releases, you can use the following command to request additional -branches: `fedpkg --module-name request-branch f27` -* When this is complete (tickets in Paquire for requests above are -closed as processed), you can -link:Join_the_package_collection_maintainers#Import.2C_commit.2C_and_build_your_package[import -your SRPM package] into the SCM. -* Checkout the package using `fedpkg clone ` do a final -check of spec file tags, etc. -* Request a Koji build by running `fedpkg build`. (You will need to set -up link:Infrastructure/Kerberos[Kerberos for Fedora project]) -* Repeat the process for other branches you may have requested above: -** Checkout given branch: `fedpkg switch-branch f26` -** Lets Koji build the package for this branch: `fedpkg build` -* Request updates for Fedora release branches, if necessary, using -`fedpkg update` or another Bodhi interface as detailed in Bodhi. -* If possible, add your package to -link:Upstream_release_monitoring[Upstream Release Monitoring]. -* You should make sure the review ticket is closed. You are welcome to -close it once the package has been built on the requested branches, or -if you built for one of the Fedora release branches you can ask Bodhi to -close the ticket for you when it completes the process. If you close the -ticket yourself, use *NEXTRELEASE* as the resolution. - -You do not need to go through the review process again for subsequent -package changes, and should not reference the review ticket in -subsequent updates you create in Bodhi. - -[[reviewer]] -=== Reviewer - -The Reviewer is the person who chooses to review a package. - -The Reviewer can be any Fedora account holder who is a member of the -[https://admin.fedoraproject.org/accounts/group/members/packager/* -packager group]. (If the Contributor is not yet sponsored, the review -can still proceed to completion but they will need to find a sponsor at -some point.) - -* Search for a review request that needs a reviewer: -http://fedoraproject.org/PackageReviewStatus/ (*fedora-review* flag is -blank or the bug is assigned to nobody@fedoraproject.org) -* If you notice some issues that need to be solved before you want to -start a formal review, add these issues in a comment and set the -Whiteboard of the bug to contain NotReady. This helps other possible -reviewers to notice that the review request is not yet ready for further -review action. -* if you want to formally review the package, set the *fedora-review* -flag to *?* and assign the bug to yourself. - -* Review the package ... -** Go through the MUST items listed in Packaging:ReviewGuidelines[ -Review Guidelines] . -** Go through the SHOULD items in Packaging:ReviewGuidelines[ Review -Guidelines] . -** The https://fedorahosted.org/FedoraReview/[FedoraReview] tool -(packaged as fedora-review) can help to automate this process. -* Include the text of your review in a comment in the ticket. For easy -readability, simply use a regular comment instead of an attachment. -* Take one of the following actions: -** *ACCEPT* - If the package is good, set the *fedora-review* flag to -*+* - -* ** *FAIL, LEGAL* - If the package is legally risky for whatever reason -(known patent or copyright infringement, trademark concerns) close the -bug WONTFIX and leave an appropriate comment (i.e. we don't ship mp3, so -stop submitting it). Set the *fedora-review* flag to *-*, and have the -review ticket block FE-Legal. -** *FAIL, OTHER* - If the package is just way off or unsuitable for some -other reason, and there is no simple fix, then close the bug WONTFIX and -leave an appropriate comment (i.e. we don't package pornography for -redistribution, sorry. Or, this isn't a specfile, it's a McDonald's -menu, sorry.) Set the *fedora-review* flag to *-*. -** *NEEDSWORK* - Anything that isn't explicitly failed should be left -open while the submitter and reviewer work together to fix any potential -issues. Mark the bug as NEEDINFO while waiting for the reviewer to -respond to improvement requests; this makes it easier for reviewers to -find open reviews which require their input. - -[[definitions-for-fedora-review-flag-settings]] -== Definitions for fedora-review Flag Settings - -[cols=",,",] -|======================================================================= -|fedora-review |(BLANK) |Package Needs Review - -|fedora-review |? |Package Under Review - -|fedora-review |- |Package Failed Review, dropped for legal or other -issues. - -|fedora-review |+ |Package Approved -|======================================================================= - -[[special-blocker-tickets]] -== Special blocker tickets - -There are a few tickets which can be placed in the "Blocks" field to -indicate specific ticket statuses: - -[cols=",",] -|======================================================================= -|FE-NEEDSPONSOR |The submitter requires a sponsor; the review can be -done by anyone, but a sponsor will need to come and sponsor the -submittor. - -|FE-DEADREVIEW |The review has been closed out because the submitter has -left; users looking for packages to submit may find some possibilities -in these dead tickets. - -|FE-Legal |The package is currently awaiting review by the legal team. -|======================================================================= - -[[the-whiteboard]] -== The Whiteboard - -To save time for reviewers, the page at -http://fedoraproject.org/PackageReviewStatus/NEW.html will hide certain -tickets which are not reviewable. The Whiteboard field can be used to -mark a ticket with various additional bits of status which will cause it -to be hidden or displayed differently. - -[cols=",",] -|======================================================================= -|NotReady |The package is not yet ready for review. It is possible to -open a review ticket, mark it as NotReady, and continue to work on it -until it's ready to be seen by a reviewer. - -|BuildFails |The package fails to build. - -|AwaitingSubmitter |The package review is stalled and cannot proceed -without input from the submitter. - -|Trivial |The package is trivial to review. See below. -|======================================================================= - -The "Trivial" status is intended to indicate packages which, as an aid -to new reviewers, are especially uncomplicated and easy to review. A -ticket should not be marked as being trivial unless: - -* The package is known to build and a link to a scratch build is -included. -* The ticket explains any rpmlint output which is present. -* The spec contains nothing which is unnecessary in modern Fedora (such -as BuildRoot:, a %clean section or %defattr). -* The spec is free from excessive or complicated macro usage. -* The spec uses only the least complicated scriptlets which are taken -directly from the Packaging:Scriptlets page. -* The package contains no daemons. -* The package is not especially security sensitive. -* The code has undergone a thorough inspection for licensing issues. -Anomalies which would be found by licensecheck should be explained. - -In short, this should be reserved only for those tickets which should be -easily approachable by someone doing their first package review. - -[[tracking-of-package-requests]] -== Tracking of Package Requests - -The http://fedoraproject.org/PackageReviewStatus[cached Package Review -Tracker] provides various review-related reports and a simple way to -search for reviews by package name or reporter name or others. - -[[authorship]] -== Authorship - -This document was originally authored by link:TomCallaway[Tom 'spot' -Callaway] in 2007 and has since been modified by many others. - -Category:Package Maintainers[Category:Package Maintainers] diff --git a/content/en-US/package-update-howto.adoc b/content/en-US/package-update-howto.adoc deleted file mode 100644 index 9493b6d..0000000 --- a/content/en-US/package-update-howto.adoc +++ /dev/null @@ -1,344 +0,0 @@ -= package update howto -This document shows how to submit an update for a package you maintain -in Fedora. It assumes you already have a package in the Fedora -repositories. It is not a guide to using the Fedora package source -control system: see the link:Package maintenance guide[Package -maintenance guide] for that. - -* For details of the policy on requirements for updates at various -stages of the link:Fedora Release Life Cycle[Fedora Release Life Cycle], -refer to link:Updates Policy[Updates Policy]. - -[[overview]] -== Overview - -This page is intended for new and existing package maintainers. Testers -and regular users may be interested in the -QA:Updates_Testing[updates-testing] repository and the -QA:Update_feedback_guidelines[update feedback guidelines]. This page -specifically covers the update submission process. - -There are two significantly different package update submission -workflows in Fedora: - -* link:Releases/Rawhide[Rawhide], and link:Releases/Branched[Branched] -up to the link:Updates Policy#Bodhi_enabling[Bodhi enabling point] -* link:Releases/Branched[Branched] releases after the Alpha change -deadline, and stable releases - -The repository layouts differ somewhat for Rawhide, Branched and stable -releases, but the update workflows split up as described above. - -[[rawhide-and-early-branched]] -== Rawhide and early Branched - -The package update workflow for Rawhide and Branched before the _Bodhi -enabling point_ is simple: - -1. Build the package with (see the -link:Package maintenance guide[Package maintenance guide] for more -details) - -This is all you need to do. Your package will appear in the next daily -compose of Rawhide or Branched and will be used in any image composes -built from that tree. - -[[later-branched-and-stable-releases]] -== Later Branched and stable releases - -At the link:Updates Policy#Bodhi_enabling[Bodhi enabling point], the -Bodhi update feedback system is enabled by -link:ReleaseEngineering[Release Engineering] and builds submitted with -are no longer automatically sent to any official -link:Repositories[repository]. The update workflow for releases of this -type is: - -1. Build the package with -2. Submit an update for the package with , the -https://admin.fedoraproject.org/updates/[Bodhi web interface], or the -https://fedorahosted.org/bodhi/wiki/CLI[Bodhi CLI tool]. This causes the -package to be sent to the -link:Repositories#updates-testing[_updates-testing_] repository -3. Monitor the update's status and the feedback you receive via the web -interface or the emails that are sent to you, and modify it with updated -or additional builds if necessary -4. After the update meets the criteria in the -link:Updates Policy[Updates Policy] and you are satisfied it should be -released as a stable update, submit the update to -_link:Repositories#stable[stable]_ with or the web interface - -[[update-attributes]] -=== Update attributes - -At the time you submit the update, you will be asked for several -attributes. The type of the update should be fairly self-explanatory: -either it fixes bugs, adds new features, or is a new package. - -If you are asked whether you want to send the update to -_updates-testing_ or _stable_, this is a no-op: all updates now go -through _updates-testing_. It does not matter what you choose. - -There are several schools of thought on filling out the update -description. Some would suggest you consider the target audience: for a -stable release, in particular, many Fedora users will see this text, and -many of them may not be particularly familiar with your package. -Consider not simply describing literally the changes in the update, but -explaining as if to an outsider why your are updating the package, what -benefits it will bring to them (if any), and anything they may want to -note in order to have a smooth update experience. - -If you associate one or more bug reports with your update, Bodhi will -post comments into Bugzilla to alert those following the bug reports -that an update is available. If you mark your update as fixing the -bug(s), Bodhi will move the report(s) through the *MODIFIED*, *ON_QA* -and *CLOSED ERRATA* states of the link:BugZappers/BugStatusWorkFlow[bug -workflow] as your update reaches various points in the process. Using -this mechanism can be very useful both for you and for users of your -package. - -You may set a _karma_ (feedback) level at which the update will -automatically be submitted to _stable_. This is optional. If you choose -to use it, please carefully consider an appropriate feedback level. For -a relatively obscure package which is quite stable, 1 or 2 may be an -appropriate value. For a popular, sensitive and complex package such as -or the , the default of 3 may be insufficient and a choice of 5 or even -10 may be appropriate. - -[[who-will-receive-your-update-when]] -=== Who will receive your update, when? - -When a release is in Branched state, the _updates-testing_ repository is -enabled by default so most users will see the package, but only packages -from the stable _fedora_ repository are used in building milestone -releases (Alpha, Beta and Final) and nightly images. - -Where a package goes when it is marked as _stable_ differs between -Branched and stable releases. In Branched releases, _stable_ packages -are pushed to the base _fedora_ repository. In stable releases, _stable_ -packages are pushed to the _updates_ repository. However, from the point -of view of the packager, this is an insignificant implementation detail. -For more details, see Repositories. - -When a release is in stable state, the _updates-testing_ repository is -disabled by default, but QA team members and others run with it enabled -in order to provide testing and Bodhi feedback. The main user population -will see your update only when it passes Bodhi, is marked as _stable_ -and reaches the _updates_ repository. - -[[updating-inter-dependent-packages]] -=== Updating inter-dependent packages - -If an update you wish to submit would cause a dependency issue of any -kind (a strict package dependency error, or simply another package -failing to operate correctly) if updated alone, you must not submit the -package as a single-package update. You must always collect all -inter-dependent or related packages together into a single multi-package -update, such that no user will face problems if they install all the -packages in the update together. - -For example: if you maintain a package _libfoo_ which the package _bar_ -depends on, and you need to update _libfoo_, you should check that _bar_ -continues to function correctly with the updated version of _libfoo_. If -it does not, you must ensure the appropriate changes are made to _bar_, -and include the updated _bar_ in your update along with the updated -_libfoo_. - -The _fedpkg_ tool does not handle multi-package updates. You can add -multiple packages to an update using the -https://admin.fedoraproject.org/updates/[Bodhi web application], or the -command line tool. You can pass as many package names as you like to the -to create a new multi-package update, or use to edit an existing update. - -It is possible you will run into problems with permissions when trying -to add builds of packages you do not have commit privileges for to an -update, or trying to add a build for a package you do have privileges -for to someone else's update. If you encounter a situation like this, -you should contact the link:ReleaseEngineering[release engineering] team -or a proven packager for help. - -You may need a _buildroot override_ to complete a multi-package update -successfully. For instance in the case described above, you may need to -rebuild _bar_ against the new _libfoo_ package and submit both packages -together as a multi-package update. However, in the normal course of -events, you would not be able to build another package against your new -_libfoo_ build until it reached the link:Repositories#stable[_stable_] -state. To resolve this dilemma, you can request a buildroot override, -which causes the _libfoo_ build to be included in the buildroot for a -short time in order to get the _bar_ package build done. - -You can request a buildroot override with bodhi: This would submit a -buildroot override with a duration of two days. Buildroot overrides are -usually granted within 15-30 minutes of submission. If you submit an -override request with the bodhi tool, it will suggest a command that -will let you monitor when the package appears in the buildroot, so you -can fire your dependent build at the appropriate time. - -You can also request buildroot overrides from the -https://admin.fedoraproject.org/updates/[Bodhi web application]. - -The link:Bodhi/BuildRootOverrides[buildroot override instructions] -explain the buildroot override process in more detail. - -[[handling-feedback-from-automated-tests]] -=== Handling feedback from automated tests - -Fedora's automated testing systems, Taskotron and OpenQA, may run -automated tests on your update. Several of the Taskotron/Tasks are -documented. The openQA tests are functional tests of some critical -Workstation and Server features. - -In the Bodhi web interface, updates have a _Automated Tests_ tab which -displays the results of all automated tests. Tests shown with a red -background failed. The tests are not all 100% accurate, but they are -fairly often correct. If you see a failure, it is a very good idea to -click on the result (which will take you to a detailed log) and -investigate the issue. If you are unsure what the test indicates, you -can contact the QA team for help. - -[[waive-a-result]] -==== Waive a result - -At present, a failure of the _dist.rpmdeplint_, _dist.abicheck_, or -_org.centos.prod.ci.pipeline.complete_ tests will prevent your update -from being released. On the update's _Details_ page in the Bodhi web -interface, the *Test Gating Status* will be shown as _N of N required -tests failed_. If you are sure such a failure is a false one, you can -'waive' the result using the tool, from the package (there is -https://github.com/fedora-infra/bodhi/pull/2095[work pending] to be able -to waiver more easily, directly from the Bodhi UI). - -You can submit a waiver for a failing result with specifying the and the -: - -  waiverdb-cli -t YOUR_TESTCASE_HERE \ - -s '{"item": "this-is-the-subject", "type": "also-this-is-part-of-the-subject"}' - -p "fedora-26" -c "This is fine" - -Example: - -  waiverdb-cli -t dist.rpmdeplint \ - -s '{"item": "python-requests-1.2.3-1.fc26", "type": "koji_build"}'  - -p "fedora-26" -c "This is fine" - -You can also waive a failing result by result's id, which you can -retrieve from resultsdb with curl. To do that, you'll need the name and -the . For example: - - curl "https://taskotron.fedoraproject.org/resultsdb_api/api/v2.0/results?testcases=dist.python-versions&item=python-alembic-0.9.7-1.fc27" | jq ".data[0].id" - -This should print out the of the failing result. You can then submit a -waiver for this failing result with - - waiverdb-cli -p fedora-27 -r YOUR_ID_HERE -c "This is fine." - -Also, if you enabled automatic stable push at a karma threshold, this -will be disabled if any automated test fails. If you have examined the -result and you are sure it is a false one and there is no problem with -the package, you may re-enable the automatic push mechanism or submit -the package to _stable_ manually once it meets the other requirements of -the link:Updates Policy[Updates Policy]. - -[[waive-the-absence-of-a-result]] -==== Waive the absence of a result - -Submitting a waiver using subject/testcase allows to waive the absence -of a result (eg. the test never ran for some reason, so there is no -result item). - -If which testcase you should be specified it is not clear/known, it is -possible to run this python script, chainging it with the corrects -parameter: - - #!/usr/bin/env python - """ Ask a question of greenwave.  """ - # Usage: either modify and set PRODUCT_VERSION and NVR_LIST and run,  - # or pass version as first arg and then NVRs as further args - import pprint - import requests - import sys - PRODUCT_VERSION = 'fedora-27' if len(sys.argv) == 1 else sys.argv[1] - NVR_LIST = [] or sys.argv[2:]  # Insert your NVRs here, or pass them via command line args - for nvr in NVR_LIST: -     url = ( -         'https://greenwave-web-greenwave.app.os.fedoraproject.org/' -         'api/v1.0/decision') -     payload = dict( -         #verbose=True, -         decision_context='bodhi_update_push_stable', -         product_version=PRODUCT_VERSION, -        subject=[{'item': nvr, 'type': 'koji_build'}], -     ) -     response = requests.post(url, json=payload) -     print("-" * 40) -     print(nvr, response, response.status_code) -     data = response.json() -     print(pprint.pformat(data)) - -The output will show that Greenwave is requiring a specific testcase to -run, but it cannot find a result for it (neither pass nor failure). So -now it is possible to submit a waiver with the specified testcase in the -output and the subject already known. - -[[troubleshooting]] -==== Troubleshooting - -If you run the tool and it gives you the following error: - -  Error: The config option "resultsdb_api_url" is required - -Edit and add the following line: - -  resultsdb_api_url=`https://taskotron.fedoraproject.org/resultsdb_api/api/v2.0 - -[[branched-milestone-freezes]] -=== Branched milestone freezes - -For a short period before each milestone release, the stable -link:Repositories#fedora[_fedora_] repository is frozen. These periods -are shown as the link:Milestone freezes[Milestone freezes] (Beta Freeze, -Final Freeze) on schedules. During these periods, builds will not be -marked _stable_ and pushed from -link:Repositories#updates-testing[_updates-testing_] to _fedora_ even -after being submitted manually or automatically. In the normal course of -events, they will be pushed after the milestone release is approved at a -Go_No_Go_Meeting. If you believe your update deserves to break a -milestone freeze, a _freeze exception_ may be granted through the -QA:SOP_freeze_exception_bug_process[freeze exception process]. Accepted -release blocking bugs are granted the same status through the -QA:SOP_blocker_bug_process[blocker bug process]. - -For more on the Fedora development process, see -link:Fedora Release Life Cycle[Fedora Release Life Cycle]. - -[[security-updates]] -== Security updates - -There is an additional process that layers over the regular update -process for bugs identified as security issues. If a bug is assigned to -you that blocks a link:Security Tracking Bugs[security tracking bug], -you must follow that process in addition to this one. - -[[new-package-submissions]] -== New package submissions - -If you want to build a new package, but you aren't sure which releases -to send it to: - -* New packages should always be built for Rawhide -* New packages can be built for Branched and stable releases if adding -them would provide value to users of those releases without significant -risk of causing harm - -The submission process for new packages, after they have passed the -Package_Review_Process and been link:Package_SCM_admin_requests[given an -SCM repository], is exactly the same as that for package updates. - -[[consider-creating-a-package-test-plan]] -== Consider creating a package test plan - -If you QA:SOP_test_case_creation[create test cases] for your package, -and QA:SOP_package_test_plan_creation[categorize them appropriately], -they will be automatically linked in Bodhi, so that testers will have -some guidance for planned update testing. - -Category:Package Maintainers[Category:Package Maintainers] diff --git a/content/en-US/what-happened-to-pkgdb.adoc b/content/en-US/what-happened-to-pkgdb.adoc deleted file mode 100644 index cfc0251..0000000 --- a/content/en-US/what-happened-to-pkgdb.adoc +++ /dev/null @@ -1,317 +0,0 @@ -[[why-pkgdb-is-being-decommissioned]] -= Why PkgDB Is Being Decommissioned - -In general, PkgDB works well for the current workflow of a package’s -lifecycle. Currently, a package has several branches that are tied to -Fedora releases such as “f24” or “f25”. These branches have implied -service levels (SLs) and end of life (EOL) dates based on the Fedora -release itself. Although the implied SLs and EOLs in these branches have -worked well for Fedora in the past, it’s becoming increasingly difficult -to juggle different application lifecycles and their dependencies’ -lifecycles under the umbrella of these limited number of SLs and EOLs, -especially when trying to keep up with upstream. In the past, we have -not been able to have different package lifecycles within a Fedora -release due to the nature of its design. With -https://docs.pagure.org/modularity/[Modularity], that will become a -reality, and Fedora packagers and module maintainers will need a new way -of branching in dist-git to enable this functionality. - -Since PkgDB was written with the old way of branching in mind, there -ended up being two logical paths forward. We could significantly rewrite -PkgDB to work with the new branching methodology, or we could migrate -PkgDB's existing functionality to other tooling. After talking with some -folks in the Fedora community, the latter seemed to be the right -approach because Fedora was moving to "Pagure over Dist-Git", and that -was going to duplicate and clash with a lot of PkgDB's functionality -anyways. - -[[how-is-pkgdbs-functionality-being-replaced]] -== How Is PkgDB's Functionality Being Replaced? - -PkgDB has two primary functions. It provides package repo ACLs, and -package related "admin requests" and "admin actions". After PkgDB will -be replaced, ACLs will be handled in -https://src.fedoraproject.org/[Pagure over Dist-Git (placeholder link)] -at the package level like you would handle a traditional code repository -on https://pagure.io/[pagure.io]. As for "admin requests" and "admin -actions", those will be replaced by a CLI tool called -https://pagure.io/fedrepo_req[fedrepo-req] (see: -https://fedorapeople.org/groups/factory2/sprint-032/mprahl-fedrepo-req-admin.mp4[a -demo]) that will submit JSON formatted tickets on your behalf to a -ticket queue in a specific Pagure project monitored by the Fedora -Release Engineering group. - -For more information on this or information on how other features in -PkgDB are being replaced, please read the "How To Make This Change" -section of the -https://fedoraproject.org/wiki/Infrastructure/Factory2/Focus/ArbitraryBranching[Arbitrary -Branching Focus Document] written by the Factory 2.0 team. - -[[helpfaqs]] -== Help/FAQs - -[[how-do-i-give-a-user-commit-access-to-a-dist-git-repo]] -=== How do I give a user commit access to a dist-git repo? - -1. Browse to your project on https://src.fedoraproject.org/[Pagure over -Dist-Git (Top Level link)] -2. Click 'browse' in the top right, to open a search box -3. Enter the package name and select the proper package from the -results -4. Click on "Settings" -5. Scroll down to "Users and Groups" -6. Click on "add user" -7. Type the username in the form -8. Select "commit" instead of the default of "ticket" to set the level -of access -9. Click "Add" - -[[how-do-i-request-commit-access-to-a-dist-git-repo]] -=== How do I request commit access to a dist-git repo? - -Email the PACKAGENAME-owner@fedoraproject.org alias asking to be given -access, or file a bugzilla bug on the package asking for access. - -[[how-do-i-request-a-new-package-or-a-new-branch]] -=== How do I request a new package or a new branch - -The ticketing functionality of PkgDB was replaced by a set of command -line tools called https://pagure.io/fedrepo_req[fedrepo-req], which are -packaged in Fedora and EPEL as -https://apps.fedoraproject.org/packages/fedrepo-req[`fedrepo-req`]. The -`fedrepo-req` command requests the creation of repositories for new -packages, and the `fedrepo-req-branch` command requests new branches for -existing packages. Please review the manual pages for information on -using these tools. - -Please note that new branch requests, when processed, will only cause -the creation of an entry in the PDC. You must then create the branch in -git manually. - -[[how-do-i-orphan-a-package]] -=== How do I orphan a package? - -Visit the package's repo in pagure and navigate to the settings for that -repo. I.e. - -https://src.fedoraproject.org/rpms/PACKAGE_NAME/settings - -Navigate down to the _Give Project_ section and "give" the project to -the "orphan" user. - -For completeness, under the _Users and Groups_ section, remove yourself -from the list. - -[[how-do-i-retire-a-package]] -=== How do I retire a package? - -Run _fedpkg retire_ in a local git checkout of the package's repo. - -[[how-can-i-watch-a-packages-commits]] -=== How can I watch a package's commits? - -Navigate to the project's repo: - -https://src.fedoraproject.org/rpms/PACKAGE_NAME - -* There should be a little icon with an eyeball in the top right. -* Click it. -* There should be a drop-down with various options for different kinds -of "watch" activity. -* The one you want should say "watch commits". - -[[how-can-i-get-added-to-the-cc-list-of-a-package-bug-reports]] -=== How can I get added to the CC list of a package bug reports? - -This used to be called "watchbugs" in pkgdb. Similar to "watchcommits", -which is addressed in the question above this one... - -Navigate to the project's repo: - -https://src.fedoraproject.org/rpms/PACKAGE_NAME - -* There should be a little icon with an eyeball in the top right. -* Click it. -* There should be a drop-down with various options for different kinds -of "watch" activity. -* The one you want is "watch issues and PRs". - -[[how-do-i-become-the-default-assignee-of-a-branch-in-bugzilla]] -=== How do I become the default assignee of a branch in bugzilla? - -File a pull-request on the -https://pagure.io/releng/fedora-scm-requests/blob/master/f/rpms[releng/fedora-scm-requests] -repo to add your FAS username. - -[[how-do-i-change-the-upstream-monitoringanitya-flag-for-my-packages]] -=== How do I change the upstream-monitoring/anitya flag for my packages? - -File a pull-request on the -https://pagure.io/releng/fedora-scm-requests/blob/master/f/rpms[releng/fedora-scm-requests] -repo to tweak the ``monitoring`` setting for your packages. - -[[how-do-i-transfer-ownership-of-a-package-to-someone-else]] -=== How do I transfer ownership of a package to someone else? - -Navigate to the project's repo's *settings* page: - -https://src.fedoraproject.org/rpms/PACKAGE_NAME/settings - -Scroll down to the "give project" section. There you can give the -package to someone else. - -[[how-do-i-adopt-an-orphaned-package-or-unretire-a-package]] -=== How do I adopt an orphaned package or unretire a package? - -For now, file a https://pagure.io/releng/issues[release engineering -ticket] with the name of the package, what you need done and in the case -of unretirement, the re-review of the package (if required). - -In the case of adopting an orphaned package, they should be able to give -it to you with the -https://pagure.io/releng/blob/master/f/scripts/distgit/give-package.py[give-package.py] -script. - -In the case of unretiring a package, they should follow the -https://docs.pagure.org/releng/sop_unretire.html[SOP for unretiring a -package]. - -[[how-do-i-find-out-who-owns-a-package]] -=== How do I find out who owns a package? - -1. Browse to the project on https://src.fedoraproject.org/[Pagure over -Dist-Git (placeholder link)] you are interested in -2. On the right side of the page, there is a heading called -"Contributors". Under that heading, there will be a username with "(main -admin)" displayed next to it. That is the owner of the package. - -[[how-do-i-find-out-the-list-of-orphaned-packages]] -=== How do I find out the list of orphaned packages? - -All orphaned packages will be owned by the "orphan" FAS user account in -https://src.fedoraproject.org/[Pagure over Dist-Git (placeholder link)]. - -You may use the user interface to view all the projects owned by the -"orphan" user, but this will include repos other than just packages -(like containers or modules): -https://src.fedoraproject.org/user/orphan[https://src.fedoraproject.org/user/orphan -(placeholder link)] - -You may use the REST API to view only the orphaned RPM repos by -visiting: -https://src.fedoraproject.org/api/0/projects?namespace=rpms&owner=orphan[https://src.fedoraproject.org/api/0/projects?namespace=rpms&owner=orphan -(placeholder link)] - -[[how-do-i-find-the-list-of-retired-packagesbranches-incomplete]] -=== How do I find the list of retired packages/branches? (incomplete) - -Retired branches are tracked in PDC by setting the "active" flag to -"false" on a branch. - -To view all packages with a master branch that is retired, you can visit -the following: -https://pdc.fedoraproject.org/rest_api/v1/component-branches/?active=false&type=rpms&name=master[https://pdc.fedoraproject.org/rest_api/v1/component-branches/?active=false&type=rpms&name=master] - -To view all retired package branches, you can visit the following: -https://pdc.fedoraproject.org/rest_api/v1/component-branches/?active=false&type=rpms[https://pdc.fedoraproject.org/rest_api/v1/component-branches/?active=false&type=rpms] - -To view all retired packages, a script will need to be written to query -PDC and perform a process of elimination. - -[[how-do-i-find-a-branchs-sls]] -=== How do I find a branch's SLs? - -A branch's SLs (termed SLA in PDC) are stored in the Product Definition -Center (PDC). An entry in PDC is required for a package to be used in a -module. As an example, if you wanted to view the Python package's SLs -for the 2.7 branch, you can visit the link below. You'll notice that the -URL contains three parameters to the request. The "type" is set to -"rpms", which filters the request down to just RPM packages. The -"global_component" is set to "python", which filters it down to only -branches belonging to any "python" component (e.g. an RPM, container, -module, etc). Lastly, the "name" is set to "2.7, which filters it down -to only "2.7" branches of components. All these filters together give -you a unique result of the Python 2.7 RPM branch. -https://pdc.fedoraproject.org/rest_api/v1/component-branches/?type=rpms&global_component=python&name=2.7[https://pdc.fedoraproject.org/rest_api/v1/component-branches/?type=rpms&global_component=python&name=2.7] - -[[how-do-i-find-what-sls-are-available-for-use]] -=== How do I find what SLs are available for use? - -All available SLs are defined in the Product Definition Center (PDC) at: -https://pdc.fedoraproject.org/rest_api/v1/component-branch-slas/[https://pdc.fedoraproject.org/rest_api/v1/component-branch-slas/] - -[[how-do-i-set-an-sl-on-my-branch]] -=== How do I set an SL on my branch? - -The SL of your branch is set when you request your branch. For more -information on requesting a branch, please review the -https://fedoraproject.org/w/index.php?title=Infrastructure/WhatHappenedToPkgdb#How_do_I_request_a_new_package.2C_a_new_branch.2C_or_to_unretire_a_package.3F[How -do I request a new package, a new branch, or to unretire a package?] -section of this FAQ. - -[[will-there-be-an-f27-branch]] -=== Will there be an "f27" branch? - -Yes, we will automatically create an "f27" branch that will in general -act like the "f26" branch but with explicit SLs that match what we would -expect from the implicit SLs of a traditional Fedora 27 release. This -means packagers don't have to change their branching strategy if they -don't want to. For f28, we intend to propose to FESCo that we do not -create global "f28" branches for all packages. - -(If one branch is suitable for multiple Fedora releases, it may be less -work for the packager to create a single branch that is used by all -those releases instead of maintaining a branch per release. To arrive at -this scenario, at some point we have to stop automatically creating new -branches for new distro releases.) - -[[in-what-circumstances-should-i-request-a-new-style-branch]] -=== In what circumstances should I request a new-style branch? - -For context, go back to review Changes/ArbitraryBranching. Traditional -Fedora dist-git branches are _named in correspondence with a release of -the distro_. "New-style" branches allow packagers to name a branch -"arbitrarily". See advice on choose a name in the next subsection. - -There could be many reasons to request a new-style branch. The primary -reason is if you'd like a branch that doesn't have an SL of a -traditional Fedora release. If for instance, you create a branch that -can serve multiple Fedora releases, that would end up being less work -for you as the packager since you only maintain one branch instead of -many with the same code base. Another instance is if your package needs -to have breaking changes that are frequent and violate the lifecycle of -a traditional Fedora release. The latter example could not, however, be -included in a Fedora release since it's SL is lower than the SL of a -release. - -[[how-should-i-name-my-branch]] -=== How should I name my branch? - -At this time, there are no restrictions on how you name your branches -except that they may not be derogatory or offensive; they may not -violate the https://getfedora.org/code-of-conduct[Fedora Community Code -of Conduct]. - -Try to use branch names that best describe the SL you are trying to -provide. For instance, if you maintain a package that is at version 2.7 -for a while, you could create a branch called "2.7" which would be -updated with every 2.7.x release upstream. Another example is if you are -always trying to package the latest upstream version, you could call -your branch "latest". It's really up to you, but just try to be -informative and considerate when choosing names. - -Requests for new branches will still pass through a member of the -'cvsadmin' group for approval. They may adopt more specific policy over -time. - -[[how-do-i-pick-an-sl-for-my-branch]] -=== How do I pick an SL for my branch? - -See https://fedoraproject.org/wiki/Module:Guidelines#SLs_and_EOLs[this -section] of the Module guidelines for information on selecting the -appropriate SLs. - -[[how-do-i-find-the-list-of-modules-that-pull-in-my-branch]] -=== How do I find the list of modules that pull in my branch? - -Try https://pagure.io/releng/pull-request/6970[this script]. From f1f35bfbc5891e8e15b78b27b3166c0eb9dd7b5c Mon Sep 17 00:00:00 2001 From: Pierre-Yves Chibon Date: Apr 10 2018 01:11:28 +0000 Subject: [PATCH 2/4] Start working on the structure of the new doc Signed-off-by: Pierre-Yves Chibon --- diff --git a/content/en-US/add_a_package.adoc b/content/en-US/add_a_package.adoc new file mode 100644 index 0000000..3c50ad9 --- /dev/null +++ b/content/en-US/add_a_package.adoc @@ -0,0 +1,4 @@ += How to get a package added to Fedora? + +This document explains how to get a software packaged for Fedora and added into +the distribution diff --git a/content/en-US/becoming_packager.adoc b/content/en-US/becoming_packager.adoc new file mode 100644 index 0000000..b4a6747 --- /dev/null +++ b/content/en-US/becoming_packager.adoc @@ -0,0 +1,6 @@ += Becoming a package maintainer + +This page documents the different steps you will want to follow to become a +package maintainer in Fedora. + + diff --git a/content/en-US/stepping_out.adoc b/content/en-US/stepping_out.adoc new file mode 100644 index 0000000..51538a9 --- /dev/null +++ b/content/en-US/stepping_out.adoc @@ -0,0 +1,8 @@ += How to step away from a package? + +This package describes the steps one would need to follow to step away from +maintainaing a package in Fedora. + +There are two cases to consider: +- The maintainer found someone to take over the package +- The maintainer did not find someone interested in taking over the package diff --git a/content/en-US/update_my_package.adoc b/content/en-US/update_my_package.adoc new file mode 100644 index 0000000..71cda16 --- /dev/null +++ b/content/en-US/update_my_package.adoc @@ -0,0 +1,4 @@ += How to update my package? + +This document describe the different steps to import and update a package in +Fedora. From 1b3a012634f70a26a34998473ce79d4ece02ea04 Mon Sep 17 00:00:00 2001 From: Pierre-Yves Chibon Date: Apr 10 2018 01:20:33 +0000 Subject: [PATCH 3/4] Add a small introduction page for packaging/packager Signed-off-by: Pierre-Yves Chibon --- diff --git a/content/en-US/introduction.adoc b/content/en-US/introduction.adoc new file mode 100644 index 0000000..0d61f47 --- /dev/null +++ b/content/en-US/introduction.adoc @@ -0,0 +1,9 @@ += Packaging: what, why and how + +What is packaging +why do we package +how to package (links) + - rpms + - modules + - flatpak + ... From db867e825092bf277781737886596b7d86e764d2 Mon Sep 17 00:00:00 2001 From: Pierre-Yves Chibon Date: Apr 10 2018 01:21:27 +0000 Subject: [PATCH 4/4] Include the questions from the whiteboard on the doc files Signed-off-by: Pierre-Yves Chibon --- diff --git a/content/en-US/add_a_package.adoc b/content/en-US/add_a_package.adoc index 3c50ad9..5eeb217 100644 --- a/content/en-US/add_a_package.adoc +++ b/content/en-US/add_a_package.adoc @@ -2,3 +2,10 @@ This document explains how to get a software packaged for Fedora and added into the distribution + +Questions to answers (unordered): +- How do I COPR? +- How can I get my project in Fedora? +- How to package this project I used? +- How to get this project I used added? +- What about EPEL? diff --git a/content/en-US/update_my_package.adoc b/content/en-US/update_my_package.adoc index 71cda16..325a256 100644 --- a/content/en-US/update_my_package.adoc +++ b/content/en-US/update_my_package.adoc @@ -2,3 +2,13 @@ This document describe the different steps to import and update a package in Fedora. + +Questions to answer here (unordered): +- How do I use stream branches? +- How to submit patches to a package I use? +- How to help maintaining this package I use? +- Who can change a package I maintain? +- Remind me how to update this package I maintain + fedpkg(/git)/koji/bodhi... +- CI integration +