From Fedora Project Wiki

m (These parentheses give examples, not an explanation)
m
Line 10: Line 10:
  
 
Modules are not required to share a 1:1 relationship with RPM Packages but can instead deliver multiple RPM Packages (such as dependencies) in order to distribute a fully functional module. However naming of the module should be based on the main service or software it aims to deliver.
 
Modules are not required to share a 1:1 relationship with RPM Packages but can instead deliver multiple RPM Packages (such as dependencies) in order to distribute a fully functional module. However naming of the module should be based on the main service or software it aims to deliver.
 +
 +
== Testing Modules ==
 +
 +
For both contributors and reviewers, the COPR infrastructure can and should be used for creating and testing modules in advance of building them formally. For any long-standing Fedora Packager, this is taking the place of "Koji scratch builds" for Modules. Why? Because modules are much trickier to track through Koji and scratch builds in Koji & MBS will be a challenging implementation. As a result, it has been deferred, perhaps indefinitely, if COPR can fill the role as well or better. 
  
 
== Review Process ==
 
== Review Process ==
Line 19: Line 23:
 
A Contributor is defined as someone who wants to submit (and maintain) a new Module in Fedora.  To become a contributor, you must follow the detailed instructions to [[Join the package collection maintainers]].
 
A Contributor is defined as someone who wants to submit (and maintain) a new Module in Fedora.  To become a contributor, you must follow the detailed instructions to [[Join the package collection maintainers]].
  
As a Contributor, you should only be creating modules out of pre-existing software in the Fedora RPM repositories which adheres to the [[Packaging:NamingGuidelines| Package Naming Guidelines]]  and [[Packaging:Guidelines| Packaging Guidelines]]. Make note that the only software allowed in official Fedora Modules must be distributed via RPMs as part of the Fedora distribution. The Module Build Service will reject attempts to build from sources not provided by Fedora's dist-git.
+
As a Contributor, you should only be creating modules out of pre-existing software in the Fedora RPM repositories which adheres to the [[Packaging:NamingGuidelines| Package Naming Guidelines]]  and [[Packaging:Guidelines| Packaging Guidelines]]. Make note that the only software allowed in official Fedora Modules must be sourced from Fedora official RPMs. The Module Build Service will reject attempts to build from sources not provided by Fedora's dist-git.
  
 
=== Module Metadata Files ===
 
=== Module Metadata Files ===
Line 109: Line 113:
  
 
The "Trivial" status is intended to indicate Modules 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 "Trivial" status is intended to indicate Modules 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 Module is known to build and a link to a scratch build is included.
+
* The Module is known to build and a link to a COPR build is included.
* The ticket explains any rpmlint output which is present.
+
* The ticket explains any yamllint output which is present.
 
* The Module contains no daemons.
 
* The Module contains no daemons.
 
* The Module is not especially security sensitive.
 
* The Module is not especially security sensitive.

Revision as of 16:43, 15 August 2017

DRAFT

Review Purpose

In order for a new Module to be added to Fedora, the module must first undertake a formal review much like the RPM Package Review process. The purpose of this formal review is to try to ensure that the module meets the quality control requirements for Fedora.

Reviews are currently done for totally new modules and every time a new module stream is created (technically, proposed to be created).

Modules are not required to share a 1:1 relationship with RPM Packages but can instead deliver multiple RPM Packages (such as dependencies) in order to distribute a fully functional module. However naming of the module should be based on the main service or software it aims to deliver.

Testing Modules

For both contributors and reviewers, the COPR infrastructure can and should be used for creating and testing modules in advance of building them formally. For any long-standing Fedora Packager, this is taking the place of "Koji scratch builds" for Modules. Why? Because modules are much trickier to track through Koji and scratch builds in Koji & MBS will be a challenging implementation. As a result, it has been deferred, perhaps indefinitely, if COPR can fill the role as well or better.

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

A Contributor is defined as someone who wants to submit (and maintain) a new Module in Fedora. To become a contributor, you must follow the detailed instructions to Join the package collection maintainers.

As a Contributor, you should only be creating modules out of pre-existing software in the Fedora RPM repositories which adheres to the Package Naming Guidelines and Packaging Guidelines. Make note that the only software allowed in official Fedora Modules must be sourced from Fedora official RPMs. The Module Build Service will reject attempts to build from sources not provided by Fedora's dist-git.

Module Metadata Files

  • If you do not have any package, container layered image, or module 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 How to get sponsored into the packager group wiki page.
  • Wait for someone to review your modulemd file! At this point in the process, the fedora-review flag is blank, meaning that no reviewer is assigned.
Idea.png
Review Swaps
If nobody comments on your review request, you might want to mail to a mailing list (for example, devel) asking for a "review swap". This is an offer to do a review of someone else's modulemd in exchange for them reviewing your modulemd. This is usually one-for-one, or can be some other private arrangement depending on the difficulty of the respective components.
  • There may be comments from people that are not formally reviewing the module, 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 modulemd file and associated files 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 modulemd. 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.
  • At this point, you need to make an SCM admin request for your newly approved Module! If you have not yet been sponsored, you will not be able to progress past this point. (You will need to make sure to request the module namespace in PackageDB)
  • Checkout the package using "fedpkg clone module/<module-name>" and do a final check of your files.
  • When this is complete, you can add relevant module files into the SCM.
  • Request a build by running "mbs-build submit" from the directory you cloned into.
  • You should make sure the review ticket is closed. You are welcome to close it once the module has been built. If you close the ticket yourself, use NEXTRELEASE as the resolution.

You do not need to go through the review process again for subsequent module changes for this module stream.

Reviewer

The Reviewer is the person who chooses to review a package.

Note.png
Comments by other people
Other people are encouraged to comment on the review request as well. Especially people searching for sponsorship should comment other review requests to show, that they know the Module Guidelines.

The Reviewer can be any Fedora account holder who is a member of the 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.)

Module Metadata File

  • 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 Module Metadata (modulemd) file, set the fedora-review flag to ? and assign the bug to yourself.
Note.png
Stepping back from a Review
If you want to step back from the review for any reason, reset the fedora-review flag to be blank and reassign the bug to the default owner of the component, which is nobody@fedoraproject.org
  • 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 module is good, set the fedora-review flag to +
Questionmark.png
Time to sponsor?
If the Reviewer is also acting as Sponsor for the Contributor, then this is the time to sponsor the Contributor in the account system
    • FAIL, LEGAL - If the module is legally risky for whatever reason (known patent or copyright infringement, trademark concerns) close the bug WONTFIX and leave an appropriate comment (e.g. linking to the corresponding entry on the Forbidden_items page). Set the fedora-review flag to -, and have the review ticket block FE-Legal.
    • FAIL, OTHER - If the module 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 (e.g. packaging and gift wrap are not the same thing, sorry. Or, this isn't a modulemd, 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.
  • Once a package is flagged as fedora-review + (or -), the Reviewer's job is done although they may be called upon to assist the Contributor with the import/build/update process and to ensure that the Contributor closes the ticket out when the process is complete.

Definitions for fedora-review Flag Settings

fedora-review (BLANK) Module Needs Review
fedora-review ? Module Under Review
fedora-review - Module Failed Review, dropped for legal or other issues.
fedora-review + Module Approved

Special blocker tickets

There are a few tickets which can be placed in the "Blocks" field to indicate specific ticket statuses:

FE-NEEDSPONSOR The submitter requires a sponsor; the review should only be done by a sponsor.
FE-DEADREVIEW The review has been closed out because the submitter has left; users looking for a Module to submit may find some possibilities in these dead tickets.
FE-Legal The Module is currently awaiting review by the legal team.

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. (Note: The Package nomenclature is carried over here and you will want to filter for "Module Review")

NotReady The Module 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 Module fails to build.
AwaitingSubmitter The Module review is stalled and cannot proceed without input from the submitter.
Trivial The Module is trivial to review. See below.

The "Trivial" status is intended to indicate Modules 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 Module is known to build and a link to a COPR build is included.
  • The ticket explains any yamllint output which is present.
  • The Module contains no daemons.
  • The Module 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 Module review.

Tracking of Module Requests

The 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. (Note: The Package nomenclature is carried over here and you will want to filter for "Module Review")