Custom Upstreams is one of Pantheon’s most powerful features. Custom Upstreams allow an organization (a university, a large company) to provide their own copy of Drupal or WordPress that includes all the modules/plugins/themes/config necessary to achieve a certain use case.
Custom Upstreams are essentially a productized way to distribute a Drupal installation profile. On a literal level, an upstream is a git repo that shares a history with all of the child sites made off the upstream. With clear rules and expectations around which files/directories are updated in the child sites (or in the upstream) you can cleanly git merge in core updates from the upstream into the child sites.
In my job I’m regularly scheduled into meetings with current or potential Pantheon customers where I give guidance on when to use upstreams. I’d like to know if anyone has more caveats/questions/disagreements with my heuristics:
IMO custom upstreams are more helpful when
- There is a large number of sites running on the shared code base
- There is a very clear line between which code is expected to change in a site-specific way
- There are clear expectations around how config changes made in the update will move into pre-existing sites.
I often discourage upstreams for reasons like
- Not enough sites. If only a handful of sites are going to use the upstream, you might not be saving any time by doing code reuse this way.
- You only want a start state. Much of the value from custom upstreams comes from the update mechanism they provide. If you just want a boiler plate start state with preferred modules/plugins/themes I think there are better ways.