council-docs/project/modules/ROOT/pages/upstream-first.adoc

= Upstream First: A Core Fedora Principle

The concept of "upstream first" is a fundamental principle within the Fedora Project.
It shapes our history, culture, and approach to contributing to the open source ecosystem.
Understanding this principle is crucial for anyone looking to contribute to Fedora and the broader Linux distribution ecosystem.


[[upstream-why]]
== Fedora's Commitment to Upstream First

Fedora, as a Linux distribution, plays a unique role as an _integrator_ of countless software components.
While Fedora develops some of its own software, its primary function is to package and deliver a cohesive operating system experience built upon the work of numerous upstream projects.

From its inception, Fedora has championed the principle of _upstream first_.
This isn't a policy or hard rule; it's a core value woven into the fabric of the Fedora community.
Fedora contributors believe that changes and improvements to open source software should, whenever possible, be shared back with the upstream projects.
This ensures that *all* users of that software, not just Fedora users, can benefit.
Ultimately, Fedora's final objective is the benefit of the user, and Fedora contributors will do what they think is best for the user, even if upstream disagrees.

Upstream first is also a pragmatic engineering principle.
By contributing changes upstream, Fedora reduces the long-term maintenance burden of carrying downstream-specific patches.
Maintaining external patch sets can become increasingly difficult as upstream projects evolve.
Embracing upstream first helps ensure the sustainability of Fedora and its contributions.

This approach has a ripple effect throughout the open source ecosystem.
Changes landed in Fedora often impact numerous downstream projects that use Fedora as a foundation.
Therefore, contributing to Fedora is a highly effective way to influence and improve the broader open source landscape, particularly within the RPM/Enterprise Linux ecosystem.

By prioritizing upstream contributions, Fedora aligns with its vision of a world where everyone benefits from free and open source software built by inclusive and welcoming communities.
This commitment extends to *all* open source software, not just Fedora itself.


[[upstream-downstream]]
== Understanding Upstream and Downstream

In the world of open source, projects often have interconnected relationships described as "upstream" and "downstream."
The _upstream_ project is the original source of the software—the foundation upon which other projects are built.
_Downstream_ projects, in turn, are those that utilize and often modify the upstream software.
Think of it like a river: the upstream is the source, and downstream projects are further along the flow, receiving and potentially altering the water.

This metaphor is essential for understanding how open source projects depend on and interact with each other.
Different development models encourage varying types of upstream/downstream relationships.

[[upstream-communication]]
=== Open Communication with Upstream

Fedora recognizes the importance of clear and open communication with upstream projects.
We believe in fostering strong relationships with upstream developers and communities, and actively seek their input and feedback.

Fedora is always open to hearing from upstream projects about how we can improve our collaboration and integration processes.
We understand that Fedora's downstream usage can sometimes create challenges or friction for upstream projects.
We encourage upstream maintainers to reach out to us if they encounter any issues or have suggestions for improvement.

Our goal is to work together constructively to find solutions that benefit both Fedora and the upstream projects we rely on.
While we cannot always accommodate every upstream request, we are committed to listening, learning, and adapting our practices to minimize any negative impact on upstream communities.

The philosophy of working upstream first doesn't end with just development.
It also encompasses a productive, positive, and respectful relationship with our upstream projects.
Our communities overlap and we want to extend our Fedora values to their project as much as we would within Fedora.
To that end we always want to deal with challenges between projects together and have clear lines of communication.

[[upstream-exceptions]]
=== When Downstream Changes Happen

While Fedora prioritizes upstream contributions, there are situations where downstream-specific changes are necessary.
These exceptions are not contradictions of the upstream-first principle, but rather acknowledgements of the complex realities of software development and distribution.

Reasons for downstream patches include:

* *Upstream Rejection*:
    Sometimes, upstream maintainers may reject a patch for various reasons, even if it's beneficial to Fedora.
    Fedora may still need to carry that patch to address a specific issue or requirement.
* *Upstream Progress*:
    Upstream projects may move forward with new features or changes that require significant adaptation in Fedora.
    Fedora may need to backport fixes or implement temporary workarounds while the downstream adaptation is completed.
* *Distribution-Specific Needs*:
    Fedora, and its downstream distributions like EPEL, may have unique requirements or constraints that necessitate downstream modifications.
    These needs might relate to specific hardware support, security considerations, or integration with other Fedora components.
* *Non-Free Blobs*:
    Fedora is committed to promoting free and open source software and building everything from source.
    Sometimes, upstream projects include non-free or pre-built binary blobs that Fedora needs to patch out to adhere to its principles.
    While Fedora may discuss potential fixes with upstream, these patches might not always be accepted if there are no suitable alternatives or if they remove functionality.

In these situations, Fedora strives to minimize the scope and duration of downstream patches, and continues to work towards upstreaming changes whenever feasible.
Understanding the reasons for downstream changes is essential for maintaining transparency and trust within the community.


[[examples]]
== Examples in Action

The principle of "upstream first" manifests in various ways.
Here are a couple of examples:

* *Packaging Improvements*:
    A Fedora packager identifies a bug or missing feature in a build toolchain.
    Instead of creating a Fedora-specific patch, they submit a patch upstream to the toolchain's maintainers.
    After review and discussion, the patch is merged upstream, benefiting all users of the toolchain and eliminating the need for a downstream Fedora patch.
* *Community Script*:
    A Fedora contributor develops a script for analyzing package data.
    They share the script publicly.
    Another contributor enhances the script with new features and submits a pull request.
    The original contributor merges the changes, making the improved script available to the entire community.
* *License Clarifications*:
    A Fedora packager discovers licensing issues with an open source project, such as unclear or non-compliant licenses for included assets.
    Instead of simply excluding the project from Fedora, they work with the upstream developers to clarify or correct the licenses.
    This ensures that the project can be included in Fedora and benefits the broader open source community by promoting license compliance.
* *Avoiding Bundled Dependencies*:
    A Fedora packager notices that an upstream project bundles a specific version of a dependency.
    Instead of using the bundled dependency, they repackage the project to use the system-wide version of the dependency.
    This ensures consistency across Fedora packages, enables rapid security patch deployment, and maintains compatibility between interdependent packages.
* *Early Testing and Bug Reporting*:
    Fedora often pioneers the integration of new software versions and libraries.
    This early adoption allows Fedora contributors to identify and report build or compatibility bugs upstream, particularly in the Python ecosystem.
    These contributions benefit the entire open source community by ensuring smoother transitions and upgrades for everyone.

These examples illustrate how upstream first fosters collaboration, shared ownership, and continuous improvement within the open source ecosystem.
We encourage you to think about how you can apply the "Upstream First" principle in your Fedora contributions.
Have a story about an upstream contribution?
Share it with the community!