Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

doc: add diagram with boot stages #5539

Merged
merged 2 commits into from
Jul 24, 2024

Conversation

aciba90
Copy link
Contributor

@aciba90 aciba90 commented Jul 24, 2024

Proposed Commit Message

doc: add diagram with boot stages

SC-1835
Fixes GH-5334

Additional Context

Test Steps

tox -e doc && (cd doc/rtd_html/ && python3 -m http.server)
open http://0.0.0.0:8000/explanation/boot.html

Merge type

  • Squash merge using "Proposed Commit Message"
  • Rebase and merge unique commits. Requires commit messages per-commit each referencing the pull request number (#<PR_NUM>)

@aciba90
Copy link
Contributor Author

aciba90 commented Jul 24, 2024

Diff:

image

Copy link
Contributor

@s-makin s-makin left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks really good!

I only have two real suggestions for changes.

  1. Can we make the diagram vertical rather than horizontal? Where it gets sized to fit on the screen width it makes the text quite small. I think a vertical approach would avoid that problem and also make it easier for people to view on smaller screens.
  2. Can we make the "Detect" box yellow as well? I think since we have the list of stages at the top, and the other four are in the larger yellow boxes, it would make it nicely correspond to the list if all the main stages looked the same as each other in the diagram

@s-makin s-makin added the documentation This Pull Request changes documentation label Jul 24, 2024
@a-dubs
Copy link
Collaborator

a-dubs commented Jul 24, 2024

Can we make the "Detect" box yellow as well? I think since we have the list of stages at the top, and the other four are in the larger yellow boxes, it would make it nicely correspond to the list if all the main stages looked the same as each other in the diagram

@aciba90 @s-makin Is "detect" an actual stage of cloud-init? If not, shouldn't it be left as is so that only official cloud-init stages are given yellow boxes?

@blackboxsw blackboxsw self-assigned this Jul 24, 2024
@blackboxsw
Copy link
Collaborator

Can we make the "Detect" box yellow as well? I think since we have the list of stages at the top, and the other four are in the larger yellow boxes, it would make it nicely correspond to the list if all the main stages looked the same as each other in the diagram

@aciba90 @s-makin Is "detect" an actual stage of cloud-init? If not, shouldn't it be left as is so that only official cloud-init stages are given yellow boxes?

@a-dubs yes "detect" is an actual stage representing what systemd-generator does in early boot which calls ds-identify in cloud-init.

@holmanb
Copy link
Member

holmanb commented Jul 24, 2024

Can we make the "Detect" box yellow as well? I think since we have the list of stages at the top, and the other four are in the larger yellow boxes, it would make it nicely correspond to the list if all the main stages looked the same as each other in the diagram

@aciba90 @s-makin Is "detect" an actual stage of cloud-init? If not, shouldn't it be left as is so that only official cloud-init stages are given yellow boxes?

A small legend which describes the differences would give the boxes and color more meaning to users.

It might make sense to break out the boot page into a "logical" main page with "implementation" sub-pages so that we can talk about the systemd implementation (and other implementations) in more detail without making the logical boot stages page too busy.

@a-dubs
Copy link
Collaborator

a-dubs commented Jul 24, 2024

+1 to @holmanb's idea about breaking out into more details sub pages. But just to be clear, that work should be captured in an issue and tackled separately, right?

Collapse ordered list of boot stages to a single line because we have them
represented in the section guide on the right column and we represent
them in the vertical flow diagram in the same order top to bottom.

- Add links to each diagram step pointing to the relevant stage section
- Add diagram explanation to Network stage documenting that SSH and serial
  console are accessible after this stage.
Copy link
Contributor

@s-makin s-makin left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM :)

@blackboxsw
Copy link
Collaborator

Taking this comment as a separate issue to follow up on separately

Copy link
Collaborator

@blackboxsw blackboxsw left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

diagram looks good. I changed diagram alignment to be top to bottom TB and provided supplemental links to various boot stage sections in this page so others can dig into details easily by clicking elements in the diagram.

@blackboxsw blackboxsw merged commit 8ceae8b into canonical:main Jul 24, 2024
24 checks passed
@aciba90 aciba90 deleted the doc-boot-stage-diagram branch July 25, 2024 07:11
holmanb pushed a commit to holmanb/cloud-init that referenced this pull request Aug 2, 2024
holmanb pushed a commit that referenced this pull request Aug 6, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation This Pull Request changes documentation
Projects
None yet
Development

Successfully merging this pull request may close these issues.

5 participants