Skip to content

Conversation

@dviererbe
Copy link
Collaborator

This commit adds a mermaid diagram that gives a
quick overview over the structure and terminology
of the Ubuntu package archive.

note: This diagram is a copy from the Ubuntu server
documentation. See the Origin footer below.

This commit also adds a sphinx mermaid extension
to render the mermaid diagram.

todo: The diagram has a low contrast in dark mode.

Origin: https://documentation.ubuntu.com/server/tutorial/managing-software/#where-do-packages-come-from
Fixes: #82

This commit adds a mermaid diagram that gives a
quick overview over the structure and terminology
of the Ubuntu package archive.

note: This diagram is a copy from the Ubuntu server
      documentation. See the Origin footer below.

This commit also adds a sphinx mermaid extension
to render the mermaid diagram.

todo: The diagram has a low contrast in dark mode.

Origin: https://documentation.ubuntu.com/server/tutorial/managing-software/#where-do-packages-come-from
Fixes: #82
@dviererbe dviererbe added the enhancement New feature or request label Feb 7, 2025
@dviererbe dviererbe added this to the 2.0 Release milestone Feb 7, 2025
@dviererbe dviererbe requested a review from rkratky February 7, 2025 14:17
@dviererbe dviererbe self-assigned this Feb 7, 2025
@prash813
Copy link

prash813 commented Feb 7, 2025

Yes the diagram looks very informative and makes relation among different terms much more intutitive

@dviererbe
Copy link
Collaborator Author

note: The linkcheck failures can be ignored

(explanation/development-process: line   60) broken    https://discourse.ubuntu.com/c/release/ - 404 Client Error: Not Found for url: https://discourse.ubuntu.com/c/release/
(reference/glossary: line 1318) broken    https://launchpad.net/~ubuntu-esm-team - 404 Client Error: Not Found for url: https://launchpad.net/~ubuntu-esm-team

They are already fixed in PR #87

@tsimonq2
Copy link
Contributor

tsimonq2 commented Feb 9, 2025

Hey @dviererbe! A few notes:

  • Splits into components should somehow make it more clear that all of those pockets have those components, not just -updates.
  • -release is a hidden pocket; only Britney knows that it exists. I'd emphasize that somehow.
  • Some more unique colors would be great, perhaps a bit of Ubuntu Orange mixed with different colors.

Great start, thanks!

@dviererbe
Copy link
Collaborator Author

dviererbe commented Feb 9, 2025

@tsimonq2

  • Splits into components should somehow make it more clear that all of those pockets have those components, not just -updates.

note: I fell like the pre-text is pretty clear on that:

Let's have a quick overview with this diagram. The general flow is that the
Archive splits into :ref:`Ubuntu series <ArchiveSeries>`. Each series is split
up into :ref:`pockets <ArchivePockets>`, and then each pocket contains four
:ref:`components <ArchiveComponents>`. If we tried to show all of this on one
diagram, it would be quite extensive, so let's take a look through a single path:

  • Some more unique colors would be great, perhaps a bit of Ubuntu Orange mixed with different colors.

note: We should include that in the scope of a new issue that also fixes the low contrast in dark mode, I mentioned above. I do not want to block the PR on a styling issue, because they can take a lot of time to get right, especially because they can trigger longer discussions with the documentation team, because they want to achieve a consistent style.

  • -release is a hidden pocket; only Britney knows that it exists. I'd emphasize that somehow.

question: I am not 100% sure what you mean by that. Do you refer to the fact that the release pocket is actually just $SERIES instead of $SERIES-release? I can very well see the release pocket in the archive and apt is also configured by default with the release pocket as a source.

note: this is documented in the suites section

Suite
-----
A combination of a series and a pocket. For example:
+---------------------+----------------------+---------------------------------+
| Suite | Series | Pocket |
+---------------------+----------------------+---------------------------------+
| ``jammy`` | ``jammy`` | :ref:`ArchivePockets_Release` |
+---------------------+----------------------+---------------------------------+
| ``jammy-security`` | ``jammy`` | :ref:`ArchivePockets_Security` |
+---------------------+----------------------+---------------------------------+
| ``jammy-updates`` | ``jammy`` | :ref:`ArchivePockets_Updates` |
+---------------------+----------------------+---------------------------------+
| ``jammy-proposed`` | ``jammy`` | :ref:`ArchivePockets_Proposed` |
+---------------------+----------------------+---------------------------------+
| ``jammy-backports`` | ``jammy`` | :ref:`ArchivePockets_Backports` |
+---------------------+----------------------+---------------------------------+

@dviererbe dviererbe added the documentation Improvements or additions to documentation label Feb 21, 2025
@dviererbe dviererbe removed this from the 2.0 Release milestone Feb 21, 2025
@rkratky rkratky merged commit d61afa6 into 2.0-preview Jun 14, 2025
0 of 3 checks passed
@rkratky rkratky deleted the feat/ubuntu-archive-diagram branch June 14, 2025 17:51
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Request for visual representation of package organization under Ubuntu distribution

5 participants