From e7c8fa9b5ff3c1f9a561d0c7d68e48c0c8d6ebfc Mon Sep 17 00:00:00 2001 From: "Justin W. Wheeler" Date: Mon, 17 Feb 2025 14:26:59 -0500 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=E2=99=BB=EF=B8=8F=20docs(project):?= =?UTF-8?q?=20Incorporate=20edits=20to=20Upstream=20First=20doc?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- .../modules/ROOT/pages/upstream-first.adoc | 32 +++++++++++++++++-- 1 file changed, 29 insertions(+), 3 deletions(-) diff --git a/project/modules/ROOT/pages/upstream-first.adoc b/project/modules/ROOT/pages/upstream-first.adoc index 62bc6e4..6e96a8c 100644 --- a/project/modules/ROOT/pages/upstream-first.adoc +++ b/project/modules/ROOT/pages/upstream-first.adoc @@ -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.