From 67b02ec83ae7500c299cf1983086afd8cf98089b Mon Sep 17 00:00:00 2001 From: Justin Smith Date: Jun 02 2020 14:46:30 +0000 Subject: Add Package Review Process page Port over page content from the Fedora Wiki with changes for readability. * Make content more concise * Note Bugzilla in section titles for sections related to Bugzilla * Move Tracking of Package Requests section to be closer to related instructions * Add page to nav configuration file --- diff --git a/guidelines/modules/ROOT/nav.adoc b/guidelines/modules/ROOT/nav.adoc index 397deaa..5e6d47e 100644 --- a/guidelines/modules/ROOT/nav.adoc +++ b/guidelines/modules/ROOT/nav.adoc @@ -16,6 +16,7 @@ * xref:LicensingGuidelines.adoc[Licensing] * xref:Meson.adoc[Meson] * xref:Naming.adoc[Naming] +* xref:PackageReviewProcess.adoc[Package Review Process] * xref:PatchUpstreamStatus.adoc[Patch Status] * xref:Per-Product_Configuration.adoc[Per-Product Configuration] * xref:PkgConfigBuildRequires.adoc[Pkgconfig Build Dependencies] diff --git a/guidelines/modules/ROOT/pages/PackageReviewProcess.adoc b/guidelines/modules/ROOT/pages/PackageReviewProcess.adoc new file mode 100644 index 0000000..944dccc --- /dev/null +++ b/guidelines/modules/ROOT/pages/PackageReviewProcess.adoc @@ -0,0 +1,184 @@ += Package Review Process +:toc: + +== Review Purpose + +In order for a new package to be added to Fedora, it must first pass a formal review. Fedora's package review process ensures that submitted packages meets baseline quality standards. + +The type of packages listed below are subject to the review process. + +* New packages +* https://fedoraproject.org/wiki/Package_Renaming_Process#Re-review_required[Renamed packages] +* Formerly deprecated packages returning to the collection +* Packages merged from the old Fedora Core repository + + +== Review Process +There are two roles in the review process: Contributor and Reviewer. + +=== Contributor +A *Contributor* submits a package for approval and offers to serve as its maintainer. + +TIP: If you would like to become a Contributor, see the https://fedoraproject.org/wiki/Join_the_package_collection_maintainers[joining instructions]. + +Submitted packages should adhere to the https://fedoraproject.org/wiki/Packaging:NamingGuidelines[Package Naming Guidelines] and https://docs.fedoraproject.org/en-US/packaging-guidelines/[Packaging Guidelines], and they should not contain https://fedoraproject.org/wiki/Forbidden_items[Forbidden Items]. + +Follow the steps below to submit a package for review. + +NOTE: Some new packages may be exempt from review. Please see the https://docs.fedoraproject.org/en-US/packaging-guidelines/ReviewGuidelines/[Package Review Guidelines] for exemption criteria. If an exemption is approved, follow the instructions in https://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=1376885[Bug 1376885], and start these instructions from step 6. + +1. Place the package's spec file and SRPM in an Internet-accessible location where they can be downloaded without having to log in or use special download methods. https://copr.fedorainfracloud.org/[COPR] can be used for this purpose. + +2. Fill out a https://bugzilla.redhat.com/bugzilla/enter_bug.cgi?product=Fedora&format=fedora-review[request for review] in https://fedoraproject.org/wiki/Bugzilla[Bugzilla], Fedora's bug tracker. The request's `fedora-review` flag is blank, which indicates that a Reviewer has not been assigned yet. ++ +NOTE: If you do not already have a package in Fedora, you will need to be sponsored by an existing member of the Fedora `packager` group. Add https://bugzilla.redhat.com/show_bug.cgi?id=177841[`Bug 177841`] to the bugs being blocked by your review request, and see https://fedoraproject.org/wiki/How_to_get_sponsored_into_the_packager_group[this article] for information on how to get a sponsor. + +3. Wait for a Reviewer to review your package. ++ +TIP: If nobody comments on your review requests, message a Fedora mailing list, such as https://lists.fedoraproject.org/admin/lists/devel@lists.fedoraproject.org/[devel], and ask for a *review swap*. In a review swap, you offer to review someone's package in exchange for them reviewing yours. The conditions for a review swap may vary depending on the complexity of the packages involved. ++ +NOTE: People who are not formally reviewing your package may leave comments or add `NotReady` to the bug's `Whiteboard` field if problems are discovered. It is expected that you will respond. Once the problems have been resolved, post the URLs to the updated SPEC and SRPM file, and remove `NotReady` from `Whiteboard`. + +4. A Reviewer agrees to review the package. The request's `fedora-review` flag is set to `?` to indicate that it is under review. Fix any problems that the reviewer identifies. + +5. The Reviewer approves the package. The request's `fedora-review` flag is set to `+` to indicate that it has passed review. + +6. In https://pagure.io/pagure[Pagure], https://pagure.io/settings/token/new[create an API token^] with the `Create a new ticket` ACL. Add it to `~/config/rpkg/fedpkg.conf` as shown below. ++ +---- +[fedpkg.pagure] +token = generated-code +---- ++ +7. Use the https://fedoraproject.org/wiki/Package_maintenance_guide[fedpkg^] tool to request a Git repository for the project. For a package named `foo` with Bugzilla ID `12345` for the package review request, run `fedpkg request-repo foo 12345`. This adds the package to https://fedoraproject.org/wiki/Releases/Rawhide[Rawhide^]. ++ +NOTE: Use `fedpkg request-branch` to add the package to additional Fedora releases. For example, to add `foo` to Fedora 31, run `fedpkg request-branch --repo foo f31`. + +8. Run `fedpkg clone foo` to check out the package. + +9. https://fedoraproject.org/wiki/Join_the_package_collection_maintainers#Import.2C_commit.2C_and_build_your_package[Import the package's SRPM^]. Do a final check of the contents. + +10. Set up https://fedoraproject.org/wiki/Infrastructure/Kerberos#Infrastructure_kerberos_authentication[Kerberos authentication^] with Fedora's instructure. + +11. Run `fedpkg build` to build the package in https://fedoraproject.org/wiki/Koji[Koji^], Fedora's RPM package build service. ++ +NOTE: If the package was added to additional Fedora releases in step 7, build each release's package. For example, to build a package for Fedora 31, run `fedpkg switch-branch f31` and then `fedpkg build`. + +12. Add the package to https://fedoraproject.org/wiki/Upstream_release_monitoring[Upstream release monitoring] to simplify tracking upstream updates. Use https://fedoraproject.org/wiki/Bodhi[Bodhi] to publish package updates. ++ +NOTE: It is not necessary to repeat the package review process for package changes. Do not reference the package's review request in updates created using Bodhi. + +13. Close the package's review request in Bugzilla. This can be done automatically using Bodhi or manually in Bugzilla. If the review request is closed manually, set its `Resolution` field to `NEXTRELEASE`. + +=== Reviewer +A *Reviewer* is a member of the Fedora https://admin.fedoraproject.org/accounts/group/members/packager/*[packager group] who reviews packages submitted by a Contributor. + +Follow the steps below to review a submitted package. + +1. Search the https://fedoraproject.org/PackageReviewStatus/[Cached Package Review Tracker] for a package that needs a reviewer. ++ +TIP: Eligible packages either have a blank `fedora-review` field or are assigned to `nobody@fedoraproject.org`. ++ +NOTE: If you notice issues that should be fixed before the package is reviewed, leave a detailed comment and set the package review request's `Whiteboard` field to `NotReady`. This alerts other possible reviewers. + +2. Set a package review request's `fedora-review` field to `?` to become its Reviewer. + +3. Review the package. It should meet the *MUST* and *SHOULD* criteria listed in the https://docs.fedoraproject.org/en-US/packaging-guidelines/ReviewGuidelines/#_things_to_check_on_review[Package Review Guidelines]. ++ +TIP: The https://pagure.io/FedoraReview[`fedora-review`] tool can help automate this process. However, it is not a substitute for manual review. You are still expected to understand the https://docs.fedoraproject.org/en-US/packaging-guidelines/[Packaging Guidelines]. ++ +NOTE: If you need to step down from being the package's review, set the package review request's `fedora-review` field to be blank and assign the bug to `nobody@fedoraproject.org`. + +4. When your review is complete, post your feedback as a comment in Bugzilla. Do not post it as an attachment. ++ +NOTE: Other users are encouraged to post comments as well. This can be especially useful for new Contributors. Demonstrating that you understand the https://docs.fedoraproject.org/en-US/packaging-guidelines/[Packaging Guidelines] may make it easier to find a sponsor. + +5. Take the appropriate action listed below. + +* *Accept*: If the package is acceptable, set the package review request's `fedora-review` flag to `+`. +* *Needs Work*: If the package has problems that you feel can be fixed, set the package review request's `Status` field to `NEEDINFO` and leave a detailed comment that explains what needs to be done. Work with the Submitter to resolve the problems. +* *Fail, Legal*: If the package has legal risks, such as copyright infringement or trademark concerns, close the package review request. Set its `Status` field to `WONTFIX`, its `fedora-review` field to `-`, and add `FE-Legal` to its `Blocks` field. Post a detailed comment that explains your decision. ("We don't ship MP3.") +* *Fail, Other*: If the package has significant problems that cannot be easily fixed, close the package review request. Set its `Status` field to `WONTFIX` and its `fedora-review` field to `-`. Post a detailed comment that explains your decision. + +6. If you approve a package review request, you may be asked to help the Contributor with the import/build/update process and to ensure that the Contributor closes the request when the process is complete. + +== Tracking Package Requests + +The https://fedoraproject.org/PackageReviewStatus/[Cached Package Review Tracker] can be used to search for reviews or retrieve reports with information on the current state of all Fedora package review requests. + +== Bugzilla Reference: fedora-review Field + +In Bugzilla, a package review request's `fedora-review` field tracks the request's status. + +[cols=2*] +|=== +|*Value* +|*Description* + +|(Blank) +|The package needs review. + +|`?` +|The package is under review. + +|`-` +|Package review has failed; the package was dropped for legal or other issues. + +|`+` +|The package has been approved. +|=== + +== Bugzilla Reference: Blocks Field + +In Bugzilla, a package review request's `Blocks` field can include values that indicate specific statuses. + +[cols=2*] +|=== +|*Value* +|*Description* + +|FE-DEADREVIEW +|The request has been closed because the submitter has left. + +|FE-LEGAL +|The request is currently awaiting review by the legal team. + +|FE-NEEDSPONSOR +|The request needs a sponsor. Package review can be performed by anyone, but a sponsor is still needed. + +|=== + +== Bugzilla Reference: Whiteboard Field + +In Bugzilla, a package review request's `Whiteboard` field can include values that will cause it to be hidden or displayed differently in the Cached Package Review Tracker's http://fedoraproject.org/PackageReviewStatus/NEW.html[new package page]. + +This saves Reviewers time by hiding tickets that are not ready for review. + +[cols=2*] +|=== +|*Value* +|*Description* + +|AwaitingSubmitter +|The package review process is stalled and cannot proceed without input from the Contributor. + +|BuildFails +|The package fails to build. + +|NotReady +|The package is not ready for review. It is possible to submit a package review request, mark it as `NotReady`, and continue to work on it until it is ready for a Reviewer. + +|Trivial +|The package is trivial to review. +|=== + +The `Trivial` status indicates that a package is suitable for review by a new Reviewer. Package review requests marked as `Trivial` must meet the criteria listed below. + +* The package is known to build, and a link to a scratch build is included. +* The ticket explains any rpmlint output that is present. +* The spec file contains nothing unnecessary in modern Fedora distributions such as `BuildRoot:`, a `%clean` section, or `%defattr`. +* The spec file is free from excessive or complicated macro usage. +* The spec file uses the least complicated scriptlets that are taken directly from the https://fedoraproject.org/wiki/Packaging:Scriptlets[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 that would be found by licensecheck should be explained.