📝🆕 docs(project): Initial commit, "Upstream First" (closes #84) #244
No reviewers
Labels
No labels
type
dev tools
type
existing docs
type
new docs
good first issue
help wanted
needs
changes
needs
reporter feedback
needs
triage
needs
vote
role
engineering
role
fca
role
foa
role
fpl
role
initiative lead
role
mindshare
scope
bug
scope
improvement
scope
new
state
approved
state
blocked
state
duplicate
state
invalid
state
wontfix
No milestone
No project
No assignees
18 participants
Notifications
Due date
No due date set.
Dependencies
No dependencies set.
Reference
council/docs!244
Loading…
Add table
Add a link
Reference in a new issue
No description provided.
Delete branch "add/upstream-first"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
This commit adds a new page that offers an explanation and overview of Fedora's place in the Fedora ecosystem. This is inspired by a request that @ankursinha asked to the Council in August 2020, and recent events with the Flatpak/OBS situation.
The goal of creating this page is an attempt at making an implicit part of our community ethos into something explicit. If we do not write it down and make sure we are clear about what we believe, how can we expect that the next generation will be able to steward the project in accordance with our values and beliefs in the betterment of Free Software? This explanation may not be perfect, but it is a first start, and it is placed prominently in our official project documentation.
Closes Fedora-Council/council-docs#84.
Metadata Update from @jflory7:
rebased onto
bb382f57deI think this is a well-written and thoughtful explanation of "upstream first." It effectively captures the philosophy and reasoning behind Fedora's approach while balancing the broader implications. It aligns well with my understanding of the principle and why Fedora prioritizes it. Kudos.
Adding to and maintaining what Upstream First means over time (i.e., how it's implemented) is critical to keeping the ethos alive.
I like it,
It is a great way to ensure changes are made available for everybody.
This is a really good explanation of the "first" aspect. I'd be interested in seeing more explanation on what's "second". Sometimes Fedora does carry downstream patches. Maybe upstream rejected something that's important to Fedora. Maybe upstream has moved on and Fedora has backported a fix. When people see these patches and question the upstream first principle, it would be good to be able to point them to an explanation of of why sometimes downstream happens.
That is a really excellent point Shaun--particularly for Fedora's downstream distributions (and projects like EPEL) which may have longer lifetimes than a given Fedora release but are "inheriting" the relationship with that upstream. In a way, it is what helps define the upstream/downstream relationship from the distribution perspective, which is distinct from that of the relationship between Fedora and it's upstreams.
I really like this wording and it's a big +1 from me with one nit which may be me over analyzing:
I read this in somewhat of an exclusive way, but not exclusive enough for it to be exclusive. IE: "We have this commitment and some others do while others don't". For this one line I'd recommend clarifying or removing ... but again, this is a nit. Well done 👍
This is a nice piece, I find it philosophically engaging. There is an added layer that you touch on, but don't lean into, that I would suggest putting more weight on: Upstream first is a pragmatic engineering principle, in that it reduces or eliminates the need to maintain an external patch set. In the early days of Linux distributions we saw many companies try to differentiate themselves by carrying special patches, but in the end the management of these patches as upstream moved in new directions added maintenance weigh, ultimately sinking the distributions. If you're in it for the long-term, you have to be upstream first, it's the only way to sustain engineering.
This is great, Justin! I hate to add a new left-menu nav item — there are too many already! — but won't block on that. There is probably a bigger reorganization which could fix that.
Other examples of upstreaming: license clarifications and fixes -- e.g. https://pagure.io/fedora-workstation/issue/463#comment-953648
Metadata Update from @jflory7:
rebased onto
d0414bda32rebased onto
d0414bda32I addressed all the above feedback points in commit
e7c8fa9b5f: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.
Should we actually use the phrase "upstream first"? That's also probably worth a discussion in itself. We didn't use that phrase in the packaging guidelines because it can be particularly ambiguous and doesn't really convey the right meaning.
@ngompa I would offer that the purpose of this new page and Pull Request is to make this ambiguous phrase into something less ambiguous. 😉 I think the phrase "upstream first" is what is historically recognized by Fedora contributors, and Fedora contributors who read this page should not be surprised by anything they read.
As I said earlier in
#commops:fedoraproject.org, my goal is for this to be as unshocking as possible. The reaction I hope to solicit is, "Duh!"LGTM!
Updated screenshot of the current draft document:
1 new commit added
📝 docs(project): Add Upstream Comms section for Upstream FirstAdded commit
73112bf569:This commit addresses feedback from @kevin in Matrix about how we engage and work together with upstream communities. It emphasizes that while we are not always going to agree with upstream's suggestions, we work hard to maintain strong, healthy relationships with our upstreams, and Fedora values the importance of working together in what we do as a community.
Metadata Update from @jflory7:
Another reason for downstream patching that IMO worth mentioning is that sometimes we need to patch out non-free or pre-built blobs. We are committed to promote free software and to build everything from sources, so while we can discuss with upstream about fixing that upstream, such patches may not be applied upstream because there are no alternatives or may strip out some features.
Also, not sure it worth mentioning here, the concept of avoid bundling dependencies ensures rapid security patches deployment and to maintain compatibility between interdependent packages, rather than relying on specific bundled versions.
1 new commit added
📝 docs(project): Add context for nonfree blobs and bundled dependencies@mattia Great feedback. I addressed these points in commit
013a145f9ejust now:This page does an excellent job of explaining Fedora’s "Upstream First" principle in a way that is both clear and engaging. It provides a solid foundation for understanding upstream and downstream relationships, making it accessible for both newcomers and experienced contributors. The emphasis on sustainability, reducing maintenance burdens, and fostering a strong open-source ecosystem really reinforces Fedora’s long-standing commitment to collaboration.
The section on "When Downstream Changes Happen" is particularly well done—it acknowledges that while Fedora prioritizes upstream contributions, there are valid scenarios where downstream patches are necessary. This balanced approach helps set expectations realistically. The "Examples in Action" section is also a great touch, as it translates theory into real-world cases that people can relate to.
A few suggestions to consider:
Make key concepts pop – Bold key terms like "upstream," "downstream," and "Upstream First" when they are first introduced to make them stand out. This will help readers quickly grasp the core ideas.
Clarify Fedora’s role – The document does a great job explaining the philosophy, but adding a small section about how Fedora practically enforces "Upstream First" in daily operations (e.g., how it interacts with upstream projects or encourages contributions) could make it even stronger.
Expand on challenges – While the section on "When Downstream Changes Happen" covers why downstream patches exist, it might be helpful to briefly touch on some of the challenges Fedora has faced with this principle in the past and how they were resolved.
More engagement at the end – The closing section is good, but it might be more effective if it directly encourages contributors to apply this philosophy in their work. A simple tweak like:
This would make the document feel more inviting and interactive.
Overall, this is a well-written and much-needed document that successfully captures Fedora’s commitment to Free Software and collaboration. A few small tweaks could make it even more engaging, but as it stands, it’s already a fantastic addition to Fedora’s documentation. Great work! 🚀
According to the packaging guidelines, all patches "SHOULD have a comment above them about their upstream status", is that what you mean? (But maybe we should break this discussion out to another place to keep a better overview in this merge request.)
There is also the Staying Close to Upstream Projects page in the packaging guidelines which touches similar points as this new (and very good) proposal. I feel like there should be links between those two documents.
Another example for benefits to the whole ecosystem: Fedora is often the first trying to build Python code with the newest software, I've seen quite a few build bugs reported and fixed upstream by Fedora contributors whenever a new Python version or important lib had some breaking changes. I think the same goes for other software stacks. This may not be relevant for the big players like bottles or obs which may have sparked the creation of this MR but for a lot of smaller or medium packages which are not tested and developed on a daily basis it is a relevant contribution. I'd argue it is even more economical if one fedora contributor fixes similar bugs in 10 packages instead of 10 developers of one package understanding and finding a fix for their project.
Thanks for the positive feedback.
In my eyes, this was sufficiently covered in the "Examples in Action" section. My goal there was to provide some concrete examples of how we interact with upstreams. If you have ideas for additions there, I am happy to hear them!
I agree this is a good point, although I do not have any immediate example on-hand from Fedora history that could demonstrate this. Of course, this could always be added in a future revision.
Good feedback. I will make this change.
IMHO, this kind of guidelines should fit into the Packaging Guidelines and not into this more philosophical document.
This doc has come up a few times. Some information is duplicated, but for the most part, they are different. Once this page is published, I would be happy to open a Pull Request on that document that cross-references to this new one.
The example with the Python ecosystem is an especially good one, and we have done close work with the Python upstream too. I will work on incorporating this feedback into the draft.
This may be a place where my ignorance on the OBS and Bottle situation is showing, but if one of the goals of this doc is to address the issues those projects have with Fedora, I don't see how that's being addressed. Isn't the issue that neither of those projects want Fedora to be packaging their applications because it causes confusion from a support perspective?
To that end I don't know how the upstream first value applies in that situation, or how you would write about it in a vague way so that it does not forever seem like this doc exists only to address this issue.
Maybe you can say something like:
I don't want to make it sound too much like its a PR thing, but maybe that helps as a starting point?
I believe this document is meant as a very general guideline / philosophy, not as means to solve any specific situation. Sorry if my message brought confusion here, I probably shouldn't have mentioned obs/bottles specifically.
I think is also important to note that we mention the "Staying close to upstream project" in the onboarding guide to new packagers of new packages
Maybe, this new document should also be commented there.
1 new commit added
📝 docs(project): Voluntary nature, early testing, positive relationsCommit
e992119d2caddresses the above feedback.I agree. Once this new page is published, I will volunteer to make a follow-up Pull Request on the other page to cross-link this new page about Upstream First.
I'm missing an actual explanation what "upstream first" means. There are examples and reasons, but no actual definition.
I'd also like to see a clear statement that fedora's final objective is the benefit of the user, and we'll do what we think is best for the user, even if upstream disagrees.
LGTM, in general it provides a good view of "what to expect". This is also what I understood of the principle.
+1
+1
Justin, the content is good, but I think some important stuff is a bit too deep currently. I'll suggest a bit of trimming and reorg:
1 new commit added
📝 docs(project): Reorder sections, clarify user focus in Upstream FirstSee commit
d1719d28cd📝 docs(project): Reorder sections, clarify user focus in Upstream First
This commit refactors the "Upstream First: A Core Fedora Principle" document to improve clarity and flow, and incorporates feedback from the community.
Changes include:
We have been collecting feedback on this document since February 15th and it has gone through several revisions of feedback. Thank you to all the community members who have helped contribute to and influence this document! I think we are in a good place to merge this and publish it officially. I want y'all to know that I really appreciate the thoughtful feedback and what we were able to define together!
Let's see how long it goes before we need to update it again. 😉
Merging! 🌊
Pull-Request has been merged by jflory7
https://docs.fedoraproject.org/en-US/project/upstream-first/