Council/council-docs
1
0
Fork 0
Code Issues 8 Pull requests Projects Releases Packages Wiki Activity Actions

📝 docs(project): Reorder sections, clarify user focus in Upstream First

Browse source 
This commit refactors the "Upstream First: A Core Fedora Principle"
document to improve clarity and flow, and incorporates feedback from the
community.

Changes include:

- Move the "Fedora's Commitment to Upstream First" section to the top to
  emphasize the core principle and its rationale.
- Integrate the key points from the "The Benefits of Upstream First"
  section into the "Fedora's Commitment to Upstream First" section,
  removing redundancy and streamlining the document.
- Add a statement emphasizing Fedora's commitment to prioritizing user
  benefit, even if it means diverging from upstream decisions.
- Minor edits for improved readability and consistency.

Signed-off-by: Justin W. Wheeler <jwf@redhat.com>
This commit is contained in:
Justin W. Wheeler 2025-04-02 10:15:53 -05:00
parent e992119d2c
commit d1719d28cd
No known key found for this signature in database
GPG key ID: 7748B15FA8FA4C7E
1 changed files with 56 additions and 58 deletions
Download patch file Download diff file Expand all files Collapse all files

114
project/modules/ROOT/pages/upstream-first.adoc
View file

@ -5,28 +5,6 @@ It shapes our history, culture, and approach to contributing to the open source
Understanding this principle is crucial for anyone looking to contribute to Fedora and the broader Linux distribution ecosystem.
[[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-benefits]]
=== The Benefits of Upstream First
Fedora's upstream-first 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-why]]
== Fedora's Commitment to Upstream First
@ -37,36 +15,31 @@ 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.
[[upstream-exceptions]]
=== When Downstream Changes Happen
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.
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.
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.
Reasons for downstream patches include:
* *Upstream Rejection*:
Sometimes, upstream maintainers may reject a patch for various reasons, even if it is 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 our 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.
[[upstream-downstream]]
== Understanding Upstream and Downstream
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.
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
@ -86,6 +59,31 @@ It also encompasses a productive, positive, and respectful relationship with our
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
@ -94,26 +92,26 @@ 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.
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.
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.
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.
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.
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.