PR#938: Add Package Review Process page - packaging-committee

packaging-committee

#938 Add Package Review Process page

Closed 4 years ago by james. Opened 5 years ago by adminix.

adminix/packaging-committee package-review-process into master

Justin Smith • 4 years ago

67b02ec

file modified

		`@@ -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]`

guidelines/modules/ROOT/pages/PackageReviewProcess.adoc

file added

+184

		`@@ -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.`

adminix commented 5 years ago

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

Metadata Update from @pbokoc:
- Request assigned

5 years ago

decathorpe commented 5 years ago

Since that link is missing from the PR description, I guess you mean this wiki page:
https://fedoraproject.org/wiki/Package_Review_Process

While it was not part of the original set of "Packaging Guidelines" wiki pages (IIRC), it might make sense to include it here. We'll probably discuss that at the next meeting (in January).

Metadata Update from @decathorpe:
- Pull-request tagged with: meeting

5 years ago

adminix commented 5 years ago

Yeah, that's the one. Ugh. Sorry for not including the link.

pbokoc commented 4 years ago

@decathorpe Hi, have you had a chance to discuss this yet?

decathorpe commented 4 years ago

@pbokoc Sorry, no. There hasn't been a meeting in three weeks or so, due to lack of quorum.

rebased onto 67b02ec

4 years ago

james commented 4 years ago

We talked about this in this weeks meeting (https://meetbot-raw.fedoraproject.org/fedora-meeting-1/2020-07-23/fpc.2020-07-23-16.01.txt):

#pr-938 Add Package Review Process page. (geppetto, 16:41:23)
LINK: https://pagure.io/packaging-committee/pull-request/938
(geppetto, 16:41:23)
No need for FPC to own this document, can leave it being commnuity
maintained. Feel free to do any changes directly (geppetto,
16:56:22)

Pull-Request has been closed by james

4 years ago

tibbs commented 4 years ago

My two cents:

I don't think this page should be buried below the packaging committee bureaucracy. It has always been a community-maintained page. It is more about bugzilla states and how to run fedpkg to import a package.

I gather there is some resistance to having things in a wiki, or in having community-maintained pages at all. If so I guess I'm behind the times, and don't want to stand in the way of progress. But this really isn't about packaging guidelines so it seems odd to lump it in with them. Plus, as seen by this ticket, FPC isn't always particularly responsive when it comes to implementing changes, making it less desirable to make it the gatekeeper for things that aren't under its umbrella.