Add stack picture and more intro
- added more to the introduction paragraph (using Bob's words from #17 (closed))
- added a stack picture
- reduced the ToC so that only the top level is shown
- moved the design section below the API docs since it's not what folks want to see first (Bob's point in #19)
Merge request reports
Activity
I find it a bit confusing about what "system" and "user" levels mean on the picture. Is it a separation based on user/root?
I can see several perspectives from it:
- user/system
- dependencies
- communication
- linking
but I feel that's a bit too much to cram on a single picture and it doesn't enlighten me apart from what I already know. Would it be a good idea to split it into multiple diagrams that take a smaller bite but make explanations simple? I can help with that.
Regarding the picture itself, this was meant to address #2 (closed).
And yes, user/system = non-privledged user/root user.
The overall goal in my mind with this picture is to show:
- Bottom to top, what runs on (or uses) what
- Identify key pieces like how the GNOME tools play a role (using GSettings, GTK+, gnome-control-center, etc.)
Does this make more sense?
-
I think this would be better done as two separate diagrams, as the usage relationships can go in too many directions. (Sorry I didn't give any concrete feedback the first time around).
- phosh uses gsettings is diagonal towards top-left
- phosh uses Rootson is diagonal bottom-left
- GTK apps can use mesa which is discontinuous bottom-left
- most apps doen't need phosh for anything
- most apps need GTK and dbus and the kernel is discontinuous top-bottom
- gsettings is tied to gnome-settings-daemon but they are disjoint
and so on. These relationships are all of different kinds - I think a single two dimensional diagram can't do them justice. It would be easier to take a close look at some subset of properties e.g. "will not run without", or "is part of the graphics stack" and then describe relationships with two or three spatial relations (on top of, to the left of, inside).
Edited by Dorota Czaplejewicz -
Ok so you think maybe having a couple of pictures like these would be better? @dorota.czaplejewicz Do these sketches accurately represent what you were thinking?
-
That's the idea - the relationship between things is clear: what's on top {needs, builds upon} the items touching from the botton. It's much simpler to read, and I hope also to create.
Now the remaining question is what ways of showing the stack are interesting? I think you've already got two important ones (phosh and friends; libraries) on your drawing, and I'd add another aspect: what is unique to the Librem 5. But that's perhaps just needed as a highlight on other diagrams. Another one would round up the communication apps: Chatty and Calls together with Hægtesse, ModemManager, and libpurple.
In your handwritten picture, you get a nice property that you don't have to clutter up things if you want to add more info. I'm guessing that people will ask "is phosh/rootston based on GTK" and instead of trying to fit it on the left, you could choose to put it on the right if that is easier to understand.
-
Since we're breaking this all up, I do really like the idea of adding one for calls/messaging.
In this new sketch:
- I added one for the communications apps
- I added a GTK pillar to the shell diagram to make it more clear that phosh is based on GTK
- I moved the kernel to be the foundation of the general apps sketch
If you think these are sufficient, then i'll go ahead and start sketching them in gimp.
-
Doesn't Chatty talk directly to ModemManager now? I'm not sure the situation on the Calls side is clear either - PulseAudio is above ModemManager, but they are really unrelated. I think there should be some horizontality between them.
Similarly, the diagram focusing around Phosh may be a bit more freeform, showing that Phosh talks to a wayland compositor (arrow?) in addition to building upon the components you already put in there.
The GTK apps diagram also shows the "builds upon" relationship from a more general perspective, so if the idea is to be a library layer diagram, I'd copy some things off the original one, by adding which applications are there, and perhaps highlighting them with a matching color to show GTK/Qt use:
Phosh - Calls - Chatty - GTK apps - Qt apps - other apps GTK[libhandy] | Qt | assorted libraries Linux
I think diagrams are a difficult task and I'm not really certain myself what data we want to convey on them, so it could be helpful for others to chime in before you spend the time to redraw them again.
-
Doesn't Chatty talk directly to ModemManager now?- Oh maybe. I thought libpurple was in the middle but perhaps @andrea.schaefer can clear this up.I'm not sure the situation on the Calls side is clear either - PulseAudio is above ModemManager, but they are really unrelated. I think there should be some horizontality between them.- Well based on the readme of Hægtesse, it sounds like hægtesse is in between the modem and PA. Since Calls uses it, I assumed the flow is Calls - PA - hægtesse - modem. @bob.ham can you confirm this is the right flow for Calls? -
I think this is better, and now GTK isn't needed in the Shell diagram.- ah yes if phosh is listed under the gnome apps picture (just added).When it comes to Communication, it will help to define: on the vertical axis, is it about the flow of data or which application depends on which?- good point. I've added a data flow axis to be more clear that it's not a build/dependency diagram but rather a data flow one. -
Getting better! One last thing for now - I think the overall result is going to be better if we don't start with the question "how to draw an architecture diagram?" but instead "what do we want the user to know at this point?". It can be broken down into "what do we want to say?" (answered with text/diagram/comment pieces), until the general one is answered. A collection of small tasks should be easier to solve than a big abstract one, and that will hopefully spare us from walking into dead ends with diagrams.
-
Oh, and in the data flow diagram - it would be much more informative if the kind of data (voice call, SMS, XMPP) was shown.
Edited by Dorota Czaplejewicz 
In my opinion this is getting completely out of control. These details should be discussed in separate MRs for specific things and the overview merged now so we have at least something in there.
If we want to do more detailed pictures (which is totall great) there should be arrows between components indicating service providers and consumers. The protocol type (DBus, WL, ...) should be shown. More like a zoom in from the general overview.
A good overview knows what can be left out and can be explained in more detailed pictures. (which we can bikeshed on one by one).
-
Yes the scope on this has grown. However, since I had already put together some additional diagrams that address specific pieces, I've added them here and some text describing them. It is also important for this page and these diagrams to be as informative and not-confusing as possible.
We can either merge this now (to have something on the intro page) or we can wait and discuss it sometime soon, at the end of the next team meeting at the latest.
Edited by Heather Ellsworth -
But why don't we merge the initial image right now™ and have the other ones in a later one. They (being more detailed) require much more discussion since e.g. thinks like "communicates" need to be spelled out (which protocoll, which direction).
The other images and texts should IMHO go into separate MRs anyway since there are different people interested in it and it's nicer if one image doesn't block the merge of the others.
-
I agree that splitting up the different pieces is going to be better than having them block each other.
My objection to the diagram that I tried to voice earlier is that there's no stated purpose it serves. "Give an overview" is so broad that I don't count it as a purpose - it ignores the crucial aspects of who will learn what from the diagram. My own experience was that I wouldn't learn much from it if I didn't already know all the details from other sources, and someone with less knowledge than me might leave even more confused, for the reasons listed above (hopefully not).
Of course, the current diagram can be committed now, but I don't think it will be much in the way of progress if the problem is not clearly stated.
-
@dorota.czaplejewicz I think the current form serves the purposes to have something to point people at to get an overview what software components we're currently using and get a rough idea where they reside in the stack. This gives people new to the project a much simpler entry.
It answers about 20 question asked in the matrix channels where people would have to go and look at individual repos otherwise and this alone is value enough for me (and I consider every question that comes up in the matrix channels that can't be answered by a link to documentation (not necessarly developer documentation) a bug in the documentation stack).
Without this our stack is completely undocumented.
Edited by Guido Gunther -
Questions from the community are a good point, and I brought it up before. They are the perfect resource we can look at to identify issues, but I didn't realize you were keeping track of them when I wrote the above. Do you mind sharing the conclusions? That would directly answer the "who" and "what" that I noted in my previous message.
added 1 commit
- 166716d8 - Revert "Add more detailed diagrams and text describing them"
mentioned in commit 1294a37b
