Docs / debugging #4578
Docs / debugging #4578
Conversation
holmanb
force-pushed
the
holmanb/docs-add-debugging
branch
2 times, most recently
from
c3a23ad
to
18fdf83
Compare
Remove duplicate content that is better described in tutorials. Add content describing how to re-run cloud-init.
Most of this content isn't useful for debugging
- Includes initial steps to take based on class of failure. - Relocate some FAQ content which is better served here.
holmanb
force-pushed
the
holmanb/docs-add-debugging
branch
from
18fdf83
to
167750b
Compare
Put reference material where it belongs. Hide implementation details in development docs.
Followup to document commit 70acb7f.
Remove duplicate content that is better described in tutorials. Add content describing how to re-run cloud-init.
Most of this content isn't useful for debugging
- Includes initial steps to take based on class of failure. - Relocate some FAQ content which is better served here.
Put reference material where it belongs. Hide implementation details in development docs.
holmanb
force-pushed
the
holmanb/docs-add-debugging
branch
from
167750b
to
9cabd92
Compare
Followup to document commit 70acb7f.
- Includes initial steps to take based on class of failure. - Relocate some FAQ content which is better served here.
Put reference material where it belongs. Hide implementation details in development docs.
Followup to document commit 70acb7f.
holmanb
force-pushed
the
holmanb/docs-add-debugging
branch
from
9cabd92
to
7328700
Compare
There was a problem hiding this comment.
Overall, a really good change. Thanks!
I left some inline comments. Additionally:
The TOC is messed up. I'm seeing multiple elements of pages being rendered in the TOC for both How-to guides and Explanation. E.g.:
Also, I would personally put 'How to debug cloud-init' into How-to guides rather than Development, because debugging is often required even if there's no cloud-init development happening.
I think I would also move Internal Files: data to reference. It might also be useful for debugging, and not just development.
|
Thanks for the review @TheRealFalcon!
I agree, which is why it was linked from the How-to section as well. It is linked from both pages, which I guess was an odd choice. I can drop the development one, I guess, though I'm not sure that I am convinced that content being categorically "how to" makes it unfit for a link from the dev docs page. Thoughts? |
|
Ah, I didn't catch that it was linked in both places. I see your point. I'm fine with it but would defer to @s-makin on that one. |
Also organize other "how to run cloud-init locally" content better. Fixes canonicalGH-4608
Also organize other "how to run cloud-init locally" content better. Fixes canonicalGH-4608
holmanb
force-pushed
the
holmanb/docs-add-debugging
branch
from
08c4e60
to
d8bce58
Compare
There was a problem hiding this comment.
Thanks for all the changes! It's looking really good and is a huge improvement over what we had before. I've left comments on a couple of the discussions, but otherwise I think your explanations make sense and am happy to accept them as-is. I found a few remaining nits and left suggestions for those, but happy to accept once those are dealt with.
Also organize other "how to run cloud-init locally" content better. Fixes canonicalGH-4608
holmanb
force-pushed
the
holmanb/docs-add-debugging
branch
from
053ada1
to
f1df532
Compare
|
Thanks @s-makin for the re-review! I think I've addressed everything! |
|
@TheRealFalcon Looks like your review is still in a "requested changes" state. I still need to apply / split out the changes in the comments in this PR into logical commits. I'm happy to do that before or after review. I haven't force pushed in case you wanted to compare from when you left off, although |
|
@holmanb , structure however you'd like. I'll re-review this one from scratch. |
This page described various topics adjacent to debugging, but not debugging itself. Organize and curate content. Create new pages describing: - performance analysis - testing new cloud-init releases on Ubuntu - Ubuntu SRU process
Put reference material where it belongs. Hide implementation details in development docs.
holmanb
force-pushed
the
holmanb/docs-add-debugging
branch
from
f1df532
to
a97d299
Compare
- New page and content describing debugging for users - New page and content documenting cloud-init's status - New page and content documenting cloud-init's exported errors - New page and content documenting cloud-init's failure states - New page and content documenting how to re-run cloud-init - New content documenting how validate user-data - New content documenting how to use cloud-init with libvirt Documents canonicalGH-4500 Fixes canonicalGH-4608
holmanb
force-pushed
the
holmanb/docs-add-debugging
branch
from
a97d299
to
c24e614
Compare
|
@TheRealFalcon Ready for review :) |
There was a problem hiding this comment.
Just what you wanted...more comments on the PR 😉
Since this PR is already very large, I'm ok saving most comments for the future. For the ones that I think really should get fixed before merging, I prepended with fix:
General note:
I don't love the use of jq in our docs. While it's very commonly used by a certain subset of developer, I wouldn't consider it to be a universal Linux tool nor does it come pre-installed on most distros. Is it that bad to show actual output? Could we add emphasis to what we're trying to highlight with styling?
| @@ -0,0 +1,46 @@ | |||
| .. _internal_files: | |||
There was a problem hiding this comment.
It's probably worth calling out some files in /run too (outside of what we mention in the log and configuration files page).
| @@ -0,0 +1,74 @@ | |||
| .. _failure_states: | |||
There was a problem hiding this comment.
I think this page could be merged with the 'Exported Errors' page, especially since the exported errors page references recoverable failures without defining them.
There was a problem hiding this comment.
Could be, but while related they are really different concepts. One is about the states of cloud-init, the other is related to extracting information if cloud-init is in one of those states. I'd rather keep them separate for now, but I'll add a link to the page since it isn't defined here - no need to re-define.
| =========================== | ||
|
|
||
| Afterthe cloud-init team creates an upstream release, cloud-init will | ||
| be released in the -proposed APT repository for a |
There was a problem hiding this comment.
I want to make a stronger case for the "pocket" terminology. Repository is fairly generic term, and can refer to pretty much any place to get software. You could talk about the "Main" or "Universe" repository along with the "-updates" or "-proposed" repository, even though "Universe" and "proposed" aren't interchangeable. "Pocket" is more specific and lets you know exactly what is being referred to. You can't really find it in Debian docs (except the glossary) because it's ubuntu-specific.
Debian defines it here:
https://wiki.debian.org/Glossary#pocket
The Archive Repository Pockets section explains it well here:
https://ubuntu.com/blog/ubuntu-updates-releases-and-repositories-explained#The_archive_repository_pockets
Pocket is found 15 times on the SRU page, vs 1 for repository:
https://wiki.ubuntu.com/StableReleaseUpdates
There's more explanation of it here:
https://wiki.ubuntu.com/SecurityTeam/FAQ#Repositories_and_Updates
It's used in other ubuntu-specific tooling like here (search pocket):
https://manpages.ubuntu.com/manpages/jammy/man1/add-apt-repository.1.html
Since pocket is an established term that is more specific than repository, I think we should be preferring it.
| @@ -0,0 +1,49 @@ | |||
| .. _stable_release_updates: | |||
There was a problem hiding this comment.
Yes, the new version is great!
That's fair. It gets really verbose especially on older series that still expect the |
Thanks for that. The blog describes it the best I've seen it so far, no objections to this request. |
This page described various topics adjacent to debugging, but not debugging itself. Organize and curate content. Create new pages describing: - performance analysis - testing new cloud-init releases on Ubuntu - Ubuntu SRU process
Put reference material where it belongs. Hide implementation details in development docs.
- New page and content describing debugging for users - New page and content documenting cloud-init's status - New page and content documenting cloud-init's exported errors - New page and content documenting cloud-init's failure states - New page and content documenting how to re-run cloud-init - New content documenting how validate user-data - New content documenting how to use cloud-init with libvirt Documents canonicalGH-4500 Fixes canonicalGH-4608
holmanb
force-pushed
the
holmanb/docs-add-debugging
branch
from
72f1e7c
to
f356f97
Compare
Thanks! I just squashed the last couple of commits and will land once tests pass. |
This page described various topics adjacent to debugging, but not debugging itself. Organize and curate content. Create new pages describing: - performance analysis - testing new cloud-init releases on Ubuntu - Ubuntu SRU process
Put reference material where it belongs. Hide implementation details in development docs.
Context
Followup to PR #4500.
Fixes #4476.
Merge type