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

📝♻️ docs(project): Incorporate edits to Upstream First doc

Browse source 
This commit incorporates a few additional changes to the original draft,
per discussion in the Pagure Pull Request comments:

* Added Section on Downstream Patches: Addressed @shaunm's excellent
  point about explaining the "second" part of "upstream first" by adding
  a new section "When Downstream Changes Happen." This section explains
  the legitimate reasons for downstream patches and emphasizes that they
  are not contradictions of the core principle.

* Clarified "Distinguishes Fedora": Removed potentially exclusive
  phrasing as per @smilner's suggestion. The focus is now on the
  practice of Upstream First, not comparisons.

* Emphasized Pragmatic Benefits: Incorporated @blc's point about the
  practical engineering advantages of upstream first, specifically the
  reduction of maintenance burden. This adds another layer of
  justification for the principle.

* Added License Clarifications Example: This example summarizes
  @mattdm's point about the importance of upstreaming license-related
  fixes. It highlights how Fedora contributors actively engage with
  upstream projects to address licensing issues, ensuring compliance and
  broader inclusion in the open source ecosystem.

* Minor Edits: Minor edits for clarity and flow.

ref: https://pagure.io/Fedora-Council/council-docs/pull-request/244

Signed-off-by: Justin W. Wheeler <jwf@redhat.com>
This commit is contained in:
Justin W. Wheeler 2025-02-17 14:26:59 -05:00
parent a40f527a6f
commit e7c8fa9b5f
No known key found for this signature in database
GPG key ID: 7748B15FA8FA4C7E
1 changed files with 29 additions and 3 deletions
Download patch file Download diff file Expand all files Collapse all files

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

@ -28,9 +28,31 @@ This isn't a policy or hard rule; it's a core value woven into the fabric of the
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.
This commitment to upstream first distinguishes Fedora from some other distributions.
While others might choose to maintain extensive downstream-specific modifications, Fedora prioritizes contributing back to the source.
When Fedora packagers make necessary changes to upstream software, they strive to have those changes integrated upstream, regardless of the software's license.
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
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 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.
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.
[[upstream-benefits]]
@ -59,6 +81,10 @@ Here are a couple of examples:
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.
These examples illustrate how upstream first fosters collaboration, shared ownership, and continuous improvement within the open source ecosystem.
We encourage you to share your own examples of upstream first contributions to this list.