Join GitHub today
GitHub is home to over 40 million developers working together to host and review code, manage projects, and build software together.Sign up
Meanings of "downstream" and "upstream" are reversed in the docs, as well as semantics of --propagate and --cascade #999
I don't think it's right. Dependencies of something are generally called upstream.
Projects depending on foo are generally downstream from foo.
As a result, options
The words "upstream" and "downstream" are rooted in production process and have well established meanings. This blog post explains it quite clearly: https://reflectoring.io/upstream-downstream/
Not sure what we can do with this though... It is quite confusing like it is now, but changing it would break backwards compatibility and become a surprise... Deprecate
First of all, saying "wrong" twice with that arrogance is not an appropiate way of pointing out what you believe it's a mistake on the docs. In this project, the way you communicate things is more important than what you say. I take it that you have good intentions and that your choice of words and abrupt sentences might be a byproduct of the social norms in your native language where such strong sentences are more common, hence to you it reads "normal". It doesn't to me, so I ask you please to be more friendly, humble and polite when interacting with either me or other contributors in this project. I'm sure we can find a way to make this communication work for both of us.
Onto the main concern raised in this ticket: the interpretations of downstream and upstream in the docs and the projects look correct to me and depend on the direction of the arrows of your build graph. If you imagine a build graph as a tree,
That being said, you can't possibly link me to a blog post of a random guy in the Internet interpreting downstream/upstream as s/he seems to like and say that the definition of both are well-established. It isn't.
The interpretation in this project is the natural interpretation based on the dictionary definition of upstream in Merriam Webster: "in the direction opposite to the flow of a stream" and likewise for downstream. This very same terminology is used in source control, see https://stackoverflow.com/questions/2739376/definition-of-downstream-and-upstream as well as download/upload. So I do consider these words to be the natural choice of describing both the actions of
I apologize if I used incorrect words. I didn't mean to come as offensive and didn't want to hurt anyone's feelings. However, I wanted to be precise in pointing out what I felt was incorrect and confusing for me.
As for the "blog post of a random guy", I pointed you to a blog post that I feel described the issue very accurately and with which I totally agree in order to save repeating the same text here. There are also nice pictures there. This blog post also agrees with all the other sources I could find, including the one you link.
The SO ticket you point actually confirms my way of understanding words "upstream" and "downstream". See the highest voted answer:
So downstream is down the information flow, upstream is up the information flow. The information flow direction is the thing that's essential here. By going downstream you add more information (more value) to something, but you depend on the upstream stuff, from which you pull (clone) from. The dependency arrows point in the opposite direction than the information flow, so I admit it can be easily confusing.
Now let's go back to multi-module example and compilation stuff and analyze how information flows there.
When you you have projects
When propagating a change, the change propagates down the information flow, not against it, upstream. By Merriam Webster: "to propagate = : to cause to spread out and affect a greater number or greater area : EXTEND". So if
Now, which arrows of the build graph do you mean? The dependency arrows? I think the disagreement comes form the fact that you refer to dependency graph and I'm referring to information flow graph. The information flow graph is reversed vs dependency graph.
BTW: I don't like the source control analogy for upstream/downstream, because dvcs allow information to flow both ways, and there is also no clear dependency graph. I can pull from the source, but I can also push things upstream back to the source. The "source" and "dependency" split is very artificial. This is different than compiling stuff, where information typically flows in one direction.
This discussion seems purely academical and I don't think there is any purpose here. Really changing the parameters right now is more unnecessary work, when there is still things to do and fix. The intellectual effort of understanding how it works in Bloop is rather negligible.
Let's maybe focus on real issues, rather than trying to prove each other wrong. We loose a lot of time and effort this way that might be directed towards something more constructive.
The discussion is not academical. This is usability stuff. Using meanings of words in a different way than the rest of the world is doing causes confusion for the users.
Yes, I agree with that. There is this initial "ok, so I need to use --cascade if I want to propagate changes downstream". Then it all works.
But on the other hand changing this is not a big deal. This is just docs + naming.
I must say
Yes, I also find cascade ok. I had a bigger issue just with the docs usage of downstream and upstream and --propagate. Seriously, I tried to use --propagate on a compile task thinking it would compile all children depending on the project and I was surprised that it means the opposite thing and goes upstream.
+1 to rephrasing the docs without using upstream/downstream.
Because the terms downstream and upstream are not confusing but relative and to use such terms correctly one has to know the answer to the question "In relation to what I am thinking". When it comes to dependency graphs those can be "A is a dependency of B" and its inversion "B depends on A".
Thinking one point of view is better than the other is not only arrogant but also ignorant of the fact that both of them can highlight different interesting/important aspects of the matter.
Also the fact that until now there wasn't a great number of complaints that the docs "are confusing" suggests that it is not a prevalent issue.
Finally, let's consider the cost VS benefits if doing this change.
What would we lose?
So, it is really a non issue until much more users start to complain about the docs being unclear. Enough time on both sides was invested in this topic while it could be solved as easily as just accepting that other points of view can also be valid.
So, thanks for bringing this issue to our attention. I hope that as the result of this discussion the direction of the flow in the dependency graph used in the docs got clearer. But before changing the established terminology, we will need much more feedback from our users.
Agreed. In bloop context, they are used always in relation to the project that is currently being compiled. The project being compiled is the reference point. Therefore, if I'm compiling project X, then the dependencies of X are upstream and the dependants of it are downstream. The documentation says "downstream dependencies" and this is a misnomer - there is no such thing like a downstream dependency, and I'm not the only one saying that - see the comments under the article I linked.
Again I agree, but some complaint has to be the first one. :)
BTW: I really like what these options do! I miss them in gradle already.
Yes, that's always a minor risk. But people who already use the project probably don't read the docs. The docs are for people who learn how to use bloop or what it can do. But I get where you're coming from and that's in my initial post I suggested we don't change the semantics of how bloop works but that we only clarify the docs. Should be pretty easy and wouldn't take much time.
You don't know how large the group of people that got confused is. I showed the docs fragments to my team-mates and most were confused by the wording. Most people generally don't report problems in the docs when it is no blocking them. Particularly the ones who are only investigating the product. Many people even don't report problems when something breaks. If too much stuff is broken, they just apply a label "not ready for production time" and they move on. Even such an extremely minor issue like lack of deb / apt package was taken as a problem in the debates about bloop that I had with some other guys in the company. Also, if the product solves a painful enough problem (and bloop does!), people would use it fine even without the docs or completely broken docs.
Please note that this project is at the moment at a very early stage, and fixing terminology in later stages when it gets more popular will be much harder and even more people would be confused by the change.
This is not a debate about point of views, and not a debate whose point of view is better. These are technical terms. Technical terms typically have or at least should have clear, unambiguous meanings. If somebody reports a problem with the docs, please do a research first or just say you don't have time now, but then leave the issue open. Closing issues with no good reason, cutting off the debate and calling somebody who wanted to help arrogant is arrogant.
Pointing out mistakes and submitting fixes is the foundation of open-source collaboration. I spotted and fixed many problems with bloop already and I managed to make it work with non-trivial 1+ MLOC java/scala project and I always spoke very highly of bloop and sbt/zinc. I'm defending it from people who said the version number should be 0.2 and not 1.x, because they tried it before me, failed miserably and just gave up. As you can see they didn't report these failures here.