Changes policy

If you know the process already, you can jump immediately to an empty Change Proposal form. For help with understanding the fields, see the change submission guidance page. Watch the Fedora Changes policy video for a quick introduction to the process.

To report an issue with the proposal template, file an issue in the pgm_docs repo.

Motivation

The motivation for the Changes process is to raise the visibility of planned changes and make coordination and planning effort easier. It is nearly impossible to follow all changes happening in a big project such as Fedora. By providing a mechanism for sharing changes, it is easier for contributors to know what is coming and to ensure that we can address impacts of changes well before the release date. Change proposals should be shared as early as possible, before the change is implemented and even in the very early state of the idea, to gather community feedback and review.

The list of accepted changes, or change set, is used by different teams across the project. For example, the change set may be used to prepare external facing materials like release notes and release announcements.

Change owners are trusted and depended upon to highlight all relevant changes. Not noting important changes (whether due to oversight, different opinion of importance, or intentionally) breaks the Change process.

The Change process is an internal planning and tracking tool, and the final release is not required to reflect all proposed changes.

Change Categories

Fedora Engineering and Steering Committee (FESCo) has defined two Change categories:

  1. Self-contained changes

  2. System-wide changes

Self-Contained Changes

A self-contained change is a change to isolated package(s), or a general change with limited scope and impact on the rest of the distribution/project. Examples include addition of a group of leaf packages, or a coordinated effort within a Special Interest Group (SIG) with limited impact outside the SIG’s functional area. Self-contained changes could be used for early idea state proposals for wider and complex changes. Creating a new Solution (e.g. a Spin/Lab) is a Self-Contained Change.

Public announcement of a new self-contained change promotes cooperation on the change, and extends its visibility. Change owners may find help from the community or useful comments. Based on the community review, the self-contained change can be updated to the system-wide change category, and the owner may be asked to provide more details and extend the change proposal page.

System-Wide Changes

System-wide changes involve system-wide defaults, critical path components, or other changes that are not eligible as self-contained changes. Promoting a deliverable to Edition status is a System-Wide Change by Council policy.

Change Proposal Sections

Table 1. Change proposal sections
Element Self-Contained System-Wide

Summary

required

required

Owner

required

required

Current status

required

required

Detailed description

required

required

Feedback

optional

optional

Benefit to Fedora

required

required

Scope/Proposal owners

required

required

Scope/Other developers

as applicable

required

Scope/Release Engineering

as applicable

required

Scope/Policies and guidelines

as applicable

as applicable

Scope/Trademark approval

as applicable

as applicable

Scope/Objective alignment

as applicable

as applicable

Upgrade & Compatibility impact

optional

required

How to test

optional

required

User experience

optional

optional

Dependencies

optional

required

Contingency plan

optional

required

Documentation

optional

required

Release notes

optional

required

Essential Communication

Fedora Packaging Committee

For changes that require modifications to the Fedora Packaging Guidelines:

  • The person or group proposing the Change is responsible for providing a first draft of packaging guideline changes to the FPC.

  • Ideally, this draft will be available as a pull request before submitting the Change proposal so that the community and FESCo can evaluate the specific changes.

Release Engineering

For all system-wide changes you must file an issue in releng pagure to check if your change requires Release Engineering involvement.

Release Engineering tickets are not required by default for self-contained changes, but may be necessary if the change involves, for example, adding a new output artifact.

Trademark Approval

If your Change may require trademark approval (for example, if it is a new Spin), file a ticket requesting trademark approval from the Fedora Council.

Change process

This is the general flow for change proposals:

  • The owner submits the change proposal by setting the wiki page to the ChangeReadyForWrangler category.

  • The Program Manager checks the proposed change page for formal correctness. This includes Release Engineering, Fedora Packaging Committee, and trademark approval tickets where necessary.

  • Once the change proposal is correct, the Program Manager announces it on the devel-announce and devel mailing lists.

  • The Program Manager files a FESCo ticket no sooner than a week after the announcement on the mailing list.

    • FESCo will vote to approve or deny a change proposal in accordance with the FESCo ticket policy. Do not implement your proposal until the FESCo vote has ended. When the Program Manager creates a tracking bug for your issue, that is your indication to proceed.

    • Any team can share their views on the devel mailing list and escalate a proposed change to FESCo. The change owner may be asked to provide more details or address proposed concerns. FESCo members are encouraged to ask questions on the mailing list instead of waiting for the meeting.

    • Optionally, FESCo assigns the change to one of the FESCo members or a trusted community member within the functional area (a change shepherd), who follows the detailed status of the change with FESCo and helps with processes within Fedora. For example, the change shepherd may communicate high-impact aspects of the change, or point out that a buildroot will be necessary. The shepherd follows the status of the change until final release.

  • Change owners are encouraged to subscribe to the FESCo ticket once it has been created by the Program Manager.

  • The Program Manager will create Bugzilla trackers in the Changes Tracking component and issues in the Release Notes repository for approved changes.

  • FESCo will re-review the status of changes one week before the beta freeze. At this time, FESCo typically decides whether to activate the contingency plan. Any change for which FESCo can’t make this decision one week before beta must include a note on its Change wiki page and tracking bug. Changes that cannot be completed will automatically be deferred to the next release and do not require re-submission unless substantial revisions are made.

In most cases, you should not submit code changes to Rawhide until after FESCo has voted to approve the proposal.

Change process milestones

Proposal submission deadline

New change proposals may be submitted using the guidelines described elsewhere and until the appropriate change proposal submission deadline. For a given release, this date is available in the release schedule and will be announced well in advance.

Changes do not have to be accepted by this deadline, but they must have been submitted to the Program Manager by then.

Code complete (testable) deadline

  • By this date, a new change must be feature complete or close enough to completion that a majority of its functionality can be tested prior the Beta release.

  • If a change proposal page specifies a change will be enabled by default, it must be so by this milestone.

  • Changes that are testable should have their tracking bug set to the MODIFIED status.

At this point, Rawhide and the immediately-upcoming "N+1" release are already separate branches. If development, testing, integration — and integration testing! — are not really all lined up by this point, there is no shame in re-targeting for the next (N+2) release. Now is the time for you to bring that to FESCo. Or, if this change is time-sensitive, but needs more resources or attention from across the community, bring that to FESCo, to the Fedora Council, and to the Fedora community at large.

Code complete (100%) deadline

  • Changes must be code complete, meaning all the code required to enable the new change is finished.

  • The level of code completeness is reflected as tracker bug state ON_QA. The change does not have to be fully tested by this deadline.

Code complete (100%) deadline coincides with the Beta Freeze date because that is the last date on which it can be ensured that a build will appear in a milestone release. The idea is really that these requirements be met in the Beta release, but due to the nature of the milestone freezes, in order to ensure this is the case, the requirements must be met by the freeze date.

Bugzilla trackers

Approved change proposals will have Bugzilla issues created by the Program Manager. The following status fields should be used to reflect the status of the change:

Table 2. Bugzilla tracker statuses
BZ Status Meaning

ASSIGNED

Change approved by FESCo

MODIFIED

Change is code complete enough to be testable

ON_QA

Change is 100% code complete
Do not close tracking bugs when a change is complete. The Program Manager will do that as part of release housekeeping.

Want to help? Learn how to contribute to Fedora Docs ›