Confusing

I always get confused when people start talking about up-stream and down-stream anything, but especially when it comes to technology. Maybe I just can't wrap my head around the analogy.

So when I talk about up-stream versus down-stream dependencies or requirements, I'm already confused. Is it even a thing?

Well, I'm going to divide package dependencies into two broad groups:

1. Supporting Requirements: Those dependencies that support the package in providing its services. This is down-stream.
2. Runtime Requirements: Those dependencies to which the package adds or provides functionality. This is up-stream.

The definition of runtime requirements may sound like an arbitrary distinction. Aren't all package requirements just requirements?

I say no. Because any given package may have some number of dependencies it needs to do whatever it is the package does, but the runtime requirements are those dependencies that are needed when the package is invoked.

An Example

For example, consider the many available packages that have been created for Django. It is not uncommon for a package's setup to include Django as a dependency.

But Django is up-stream. That is, the package adds functionality that may be used withing the framework. SuperDjango requires a number of third-party packages. It also requires Django, but not until it's actually used in a Django project.

Development of the package does require Django to be installed, at least for code completion and testing, but the dependency is not required until the package is actually used, e.g. at runtime.

In such cases, the runtime dependencies are implicitly required and will almost certainly be installed before usage is invoked. That is, I never want a third-party app to install a critical dependency (like Django).

Why Does it Matter?

Including a runtime dependency (for example, in setup.py) can mean, among other things, that a critical dependency is changed for the entire project. This can create havoc for an otherwise stable project.

The simple alternative is to indicate (in the README, for example) that the dependency is required and what version is supported.