---
# System prepended metadata

title: Improving the package review process - Requirement document
tags: [Fedora, Requirements Document]

---

# Improving the package review process - Requirement document

###### tags: `Requirements Document` `Fedora`

[toc]

## Point of contacts

**CPE Appointed Owner**: pingou  
**CPE Appointed Manager**: To help unblock  
**CPE Collaborators**:   
**Key Stakeholder**: FPC, tibbs? nirik?  
**IRC Channel**: #fedora-apps  
**Taiga Link**:  
**hackmd Link**: https://hackmd.io/s/BkljfknaV

## Document History

It is important to keep track of the evolution of the requirements document. Here, we can track key changes and milestones.

**Version**: 1.0 - 2019-05-29  
**Authors**: pingou  
**Details**: First work on this proposal

## Requirements Guidelines

When writing a requirements document intended for the CPE team, a number of key items need to be included in order to help with initial reviews and later prioritization and scheduling. 
 
The following sections are required before this doc is ready for the team to consume. An example spec for reference is the Rawhide Gating [spec](https://fedoraproject.org/wiki/Infrastructure_2020/Rawhide_Gating). The sections below are not exhaustive, and the CPE team should evolve them based on their domain knowledge. The principle of each heading in this Template should be used to guide the requirements. If a heading is omitted, the spirit of what it is trying to achieve should be included in other sections.

## Goals 

The package review workflow is a long and cumbersome process which practically can not invole any of the tooling the packager will have to deal with once the package is approved (this is especially true for new packagers).
Moving the package review process out of bugzilla and into pagure would already expose the new packager to some of the tooling they will have to use and deal with.

## Value Proposition & Background

Building the package review process around pagure on dist-git allows for more automation in it, exposes the packager to some of the tools that are now core to the packager workflow and may help simplify it.

## Who is requesting this

The Fedora community.

## Assumptions

We want to avoid surprises to the development team in the middle of working on a request. At best a surprise can add more time to a project, at worst, it can lead to it failing. A big part of protecting both the team and indeed the feature being requested is calling out any Assumptions that the requester is making while putting together the spec. 
 
 
| Assumption | Raised By | Plan of Action |
|:------ |:----------- |:----------- |
| Everyone agrees with moving package review off bugzilla | pingou | Send the proposal to the devel list for feedback
| Legal agrees with putting non-approved content in forks in pagure | pingou | Get feedback from legal/spot
| ... | |

## User Stories

A set of overview User Stories which covers the requested feature/enhancement in full. The details here can be at a high level and initially do not need to have Acceptance Criteria at this point in time.

### Actors

We have identified three actors:

* Packager: whether new or not, they are the people responsible for maintaining packages in Fedora.
* Reviewer: people who are already in the packager group and thus granted by the Fedora community the trust to review packages before they enter in the distribution.
* Legal representative: Community member allowed to veto packages from entering in the distribution for legal reasons.

### User Stories

| Story Number | Group | User Story | Importance | Acceptance Criteria
|:------------ |:----- |:---------- |:-----------|:-------------------|
|1 | | As a new packager, I want to learn as early as possible with the tools I'll have to deal with |  |
|2 | | As a packager, I do not want to wait for a packager to get some feedback on my review | |
|3 | | As a reviewer, I do not want to do manually checks that can be automated  | |
|4 | | As a reviewer, I want to limit my work to the minimum | |
|5 | | As a legal representative, I want to be able to block a package review | |
|6 | | As a reviewer, I want to be able to close a review without approving it | |
|7 | | As a submiter, I want to be able to close a review | |
|8 | | As a submiter, I want to open a review without waiting on any one | |
|9 | | As a submiter, I want feedback as early as possible | |

## Open Questions

Please log and track any Open Questions here

## Risks Identified

Have we identified any risks for this work that we need to be aware of?

## Technical decisions

Here is the proposed workflow that will help fullfill the user stories presented above and help improve the package review process.

1. New packager opens a ticket on pagure.io/package-review following a defined format/template
2. New packager can tag the ticket as "New packager" indicating they need to be sponsored into the packager group
3. New packager can mark the ticket/reviews as depending on one another
4. A **bot** automatically creates a corresponding project on src.fedoraproject.org with access restricted to the releng user
5. New packager forks the project, push their change/spec file and open the corresponding pull-request
6. A **bot** runs basic checks against the spec file to provide feedback as early as possible
    * rpmlint
    * koji scratch build
    * fedora-review? (all or parts of it?)
7. New packager links to the pull-request in the original ticket
8. Reviewer self-assign the ticket opened
9. Reviewer performs the review in the pull-request
10. Reviewer can tag the ticket as waiting on "legal"
11. Review approves or rejects the package
    * Reviewer approves the package by closing the ticket as approved
        * A **bot** merges the pull-request and give the project to the user who opened the pull-request
    * Reviewer rejects the package by closing the ticket as rejected
        * A **bot** closes the pull-request without merging it and delete the main project and its clones

## Descoped

We don’t throw things away. The User Story list above should be our Minimum Viable Product (MVP), anything descoped should be copied from the Table above to the Table here so we can potentially have a Phase II.

| Story Number | Group | User Story | Importance | Acceptance Criteria
|:------------ |:----- |:---------- |:-----------|:-------------------|
|... | | | |

## Decision Log

Have we come to any important decisions that need to be recorded here for longer term consideration and as a point of reference?

## Next Steps

The initial User Stories will be explored by the team and the stakeholder who has requested the story. The initial stories will act as a conversation point and will be used as a guideline to create more Stories of varying granularity. The goal here is to have a more fleshed out story list which will serve as the starting point of formal requirements. The goal here is to examine the Minimum Viable Product (MVP) which is the minimum set of features and functionalities which represents the critical path for development. The goal here is to have a version of the feature available as early as possible and release it in phases. The overall requirements can then be documented in a similar manner to the sample below. This will allow us to schedule work on the items in a fact based manner, with estimations and schedules being derived from a completed requirements list.