Page MenuHomeSoftware Heritage

Add the beginning of a top-level architecture document
ClosedPublic

Authored by douardda on Nov 16 2018, 5:09 PM.

Diff Detail

Repository
rDDOC Development documentation
Branch
doc-archi
Lint
No Linters Available
Unit
No Unit Test Coverage
Build Status
Buildable 2432
Build 2985: arc lint + arc unit

Event Timeline

What do the pipe in |swh| mean?

Regarding docs/images/general-architecture.svg: I really like it. Could you add the names of involved technologies (eg. in a box with logo->name matching) so they are easier to search later on?

Regarding mermaid graphs: The text is too small to read without zooming in. Increasing the font size should fix that without breaking the layout.

docs/architecture.rst
8

Missing a closing parenthesis.

40

and inserts nodes and edges in the graph.

65

"seauence"

73

"gitlba"

docs/glossary.rst
33

maybe explain the difference between a SHA1 and “git-like” SHA1 in that glossary as well?

vlorentz added inline comments.
docs/glossary.rst
137

Don't forget this :)

This revision now requires changes to proceed.Nov 16 2018, 5:39 PM
docs/architecture.rst
11

Postgresql

31

choreography

43

information (it's uncountable)

docs/glossary.rst
122

prioritization

Fix reported typos and remarks

It's perfect now :)

Thanks!

This revision is now accepted and ready to land.Nov 19 2018, 1:41 PM

Several modifications

Summary:

  • replace mermaid with plantuml
  • use sphinxcontrib.images
  • better glossary

Several modifications

Summary:

  • replace mermaid with plantuml
  • use sphinxcontrib.images
  • better glossary

The diff to the previous iteration looks fine to me!

Regarding the glossary, we also had https://wiki.softwareheritage.org/wiki/Glossary ; once this is pushed the wiki glossary should be deprecated/deleted in favor of the docs.s.o one. In the meanwhile there might be entries there that are missing here (I haven't checked, but wanted to mention potentially useful previous work :-))

In D668#14654, @zack wrote:

Regarding the glossary, we also had https://wiki.softwareheritage.org/wiki/Glossary ; once this is pushed the wiki glossary should be deprecated/deleted in favor of the docs.s.o one. In the meanwhile there might be entries there that are missing here (I haven't checked, but wanted to mention potentially useful previous work :-))

I've seen this. Ok to deprecate it ASA this diff is published and the doc is online.

In fact, there are other place(s) where we can find kind of partial glossaries, especially https://docs.softwareheritage.org/devel/swh-model/data-model.html#software-artifacts . Not sure how to deal with this later one however. It makes sense to keep these definitions explicitly in this document, IMHO.

In fact, there are other place(s) where we can find kind of partial glossaries, especially https://docs.softwareheritage.org/devel/swh-model/data-model.html#software-artifacts . Not sure how to deal with this later one however. It makes sense to keep these definitions explicitly in this document, IMHO.

Agreed.

I think we can walk the fine line between a glossary (short definition, for mnemonic use) v. definition (long definition, with all the details). The Data Model can very well be the source for the latter; the glossary for the former. And for each of the relevant entries the glossary can link to the Data Model under a "for more information see [...]" notice.

This revision was automatically updated to reflect the committed changes.