Add first draft for blog post on fork/upstream relationship #886
Conversation
| In this type of forks, we usually try to not diverge too much from upstream to benefit from new features, | ||
| and we regularly sync with them. | ||
| A major downside is that syncing will often come with gnarly git conflicts. | ||
| An example of this is various organizations forking the Carpentries workbench to customize the look and feel or their internal Carpentries-style training materials. |
There was a problem hiding this comment.
TODO: Add link to Carpentries-style lessons listing
There was a problem hiding this comment.
First sentence of 2. should have similar structure to 1. where the main contrast is we don't want to diverge, and then say upstream source does not want to incorporate our adaptations.
There was a problem hiding this comment.
I also think it would be fantastic to link to your own forked version of this so folks can see what it looks like in action. ... haha I see that below.
| Alternatively, upstream can sometimes stop tracking auto-generated files from git, | ||
| and instead render them on the fly at build time. |
There was a problem hiding this comment.
TODO: Propose this in varnish and link from here
| --- | ||
| slug: "forks-upstream-relationship" | ||
| title: The dynamic relationship of forks with their upstream repository | ||
| date: '2024-12-08' |
There was a problem hiding this comment.
Determine authoring policy: everyone in the comm call or only whoever gives feedback on this draft?
There was a problem hiding this comment.
I think it's find to keep it to those who contribute/review this post specifically. I don't have a strong opinion on this, however, except that I think people can only be authors if they've reviewed the post and somehow "approved" their authorship 😁
| What are the strategies to minimize the conflicts? | ||
| And why is it in the interest of everyone (the fork owners, but also upstream maintainers) to minimize them? | ||
|
|
||
| ### Simplifying syncs and reducing git conflicts {#simplifying-syncs} |
There was a problem hiding this comment.
I think this section could benefit from code examples or illustrations. There are links to PRs but something in the post itself may also help.
There was a problem hiding this comment.
Hugo, so fantastic that you've written this up, and as usual, your ideas come across really well. I think it would be good if you're comfortable with it to centre yourself earlier in the post. Saying more about your motivation to fork the workbench (more in one of my comments). This can make it relatable to a broader audience where there's a real protagonist living through this, and coming up with a set of ideas.
I'd love to do a final review before publishing.
Thank you so much for the discussion and for doing this. And to @steffilazerte for hosting the awesome coworking sessions!!
| and they are minified on a single line, which means git cannot distinguish what was changed. | ||
|
|
||
| But you can automate the conflict resolution for these cases. | ||
| The key is to make automated changes in a separate commit. |
There was a problem hiding this comment.
can you link to an example commit? So ppl can see and copy approach, rather than having to imagine how to do it
| Note that this is not always possible as upstream may have a restricted scope, or limited resources for maintenance. | ||
|
|
||
| Forks are sometimes intended from the start as short-lived. | ||
| They only exist until the PR is merged when the user cannot wait for the PR to be merged, especially if upstream is slow to review PRs. |
There was a problem hiding this comment.
| They only exist until the PR is merged when the user cannot wait for the PR to be merged, especially if upstream is slow to review PRs. | |
| They only exist until the PR to upstream is merged when the user cannot wait for the PR to be merged, especially if upstream is slow to review PRs. |
There was a problem hiding this comment.
needs some clarification
|
|
||
| ### It takes two to tango | ||
|
|
||
| Getting forks to contribute back is only possible is they can stay in touch with upstream. |
There was a problem hiding this comment.
| Getting forks to contribute back is only possible is they can stay in touch with upstream. | |
| Getting forks to contribute back is only possible if they can stay in touch with upstream. |
There was a problem hiding this comment.
maybe add a comment on value of communicating your intent up front with the upsteam source? "I'd like to contribute back to upstream. Does the project have the capacity for this (merging PRs in a timely way). How could that work for you?"
|
|
||
| While sometimes presented as a fracture, forks are an integral part of the open-source ecosystem. | ||
| They offer a way to build on existing projects, to add extra features without increasing the maintenance burden of the upstream repository, to pilot new features. | ||
| They can be hard to maintain, but it is also possible for the fork and upstream maintainers to work together to make the process smoother. |
There was a problem hiding this comment.
Maybe at bottom have a call to action asking people to consider what projects they are planning that could be forked. Code, lessons, documentation. Do they envision diverging or contributing back? With this info in the post how might they approach it.
There was a problem hiding this comment.
Hi @Bisaloo,
Sorry it took me a bit longer to get to than I had hoped.
Thanks for writing this! Also for the lovely comments about coworking, that makes me very happy to hear!
I agree with Stef's comments in general and have added some of my own. My main suggestions are to clarify a bit the section "Contributing back to upstream" (as Stef suggested), and also to consider in what ways can the maintainers of forks work with upstream maintainers to keep things smooth? As you say, it takes two to tango, but most of your comments reflect what upstream can do differently. In particular, I really liked Stef's suggestion to communicate with the upstream maintainers. Alternatively, it's totally fine to focus on what upstream maintainers can do, but then I would perhaps reframe the context a bit at the start to make this clear.
- post follows Content Guidelines
- post follows Style Guide
- title is in Title Case
- publication date is ok -> We'll pick a date close to when you're ready, no hurry!
- author metadata is provided with correct folder name -> I'll check again when you have authors
- html not included in pull request of Rmd post
- I ran
roblog::ro_lint_md()on index.md - I ran
roblog::ro_check_urls()on index.md - I ran a spell-check on index.md
- YAML subject tags are ok ("tech notes" for tech notes; "community" for non-staff non-editor)
- YAML field 'editor' is filled with your name
- YAML field 'preface' is present if necessary
| --- | ||
| slug: "forks-upstream-relationship" | ||
| title: The dynamic relationship of forks with their upstream repository | ||
| date: '2024-12-08' |
There was a problem hiding this comment.
I think it's find to keep it to those who contribute/review this post specifically. I don't have a strong opinion on this, however, except that I think people can only be authors if they've reviewed the post and somehow "approved" their authorship 😁
|
|
||
| This blog post summarizes some of the insights that emerged during the subsequent discussion. | ||
|
|
||
| ## The different types of forks |
There was a problem hiding this comment.
It might be worth having a very brief explanation of what a fork is to those who might not know, or even though they may have heard the term, may be a bit hazy on it's meaning.
| and we regularly sync with them. | ||
| A major downside is that syncing will often come with gnarly git conflicts. | ||
| An example of this is various organizations forking the Carpentries workbench to customize the look and feel or their internal Carpentries-style training materials. | ||
| This is also what typically happens when open-source projects are packaged in Operating System distributions, such as Debian. |
There was a problem hiding this comment.
I'm on Linux, so I thought immediate, "Oh right, that's exactly what's going on there", but I can appreciate that it's not a common situation.
| The previous sections highlighted how much work maintaining a fork. | ||
| Is it possible to integrate the features to upstream and avoid having to maintain a fork? | ||
|
|
||
| Forks can be a good way to pilot new features or approaches. |
There was a problem hiding this comment.
Which can be then integrated back into the upstream?
|
|
||
| Forks are sometimes intended from the start as short-lived. | ||
| They only exist until the PR is merged when the user cannot wait for the PR to be merged, especially if upstream is slow to review PRs. | ||
| In this case, the fork is already contributing back to upstream. |
|
Here just to say how happy it makes me to be in a PR review with @steffilazerte ❤️ |
Co-authored-by: Stefanie Butland <[email protected]> Co-authored-by: Steffi LaZerte <[email protected]>
| 1. Forks can be used as a starting point for a new diverging project, rather than starting from scratch. | ||
| In this situation, the fork author does not intend to sync with the upstream repository after the initial fork. | ||
| This type of fork may therefore miss out on new features developed in upstream. | ||
| This type of fork will often happen when you copy a template for a personal website (an example shared by Will Gearty in our discussions), |
There was a problem hiding this comment.
TODO: add link to Will's online presence if he doesn't end up as an author
|
Confirming that we'd love to cross-post this on the Openscapes blog! I can copy directly from the GitHub source of the post. |
|
Awesome! As Hugo is on holidays and I'm taking holidays shortly, we decided not to rush this post and will pick it back up in the New Year. |
Moving the conversation here for transparency. I briefly pitched this to Stef & Steffi already.
In terms of timeline:
With end of year holidays coming up, this likely means this won't be finalized before early 2025.
Checklist:
I have added the "tech notes" tag if this is a technote.roblog::ro_lint_md()on index.md (optional).roblog::ro_check_urls()on index.md (optional).