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

Add new tutorial on managing software #57

Merged
merged 5 commits into from
Oct 18, 2024
Merged

Conversation

s-makin
Copy link
Collaborator

@s-makin s-makin commented Sep 26, 2024

This tutorial, aimed at newer Ubuntu users, should provide a comprehensive walkthrough of
managing software, which explains many of the terms and concepts they need to know
to use the rest of the content of the server docs and help them be successful.

Note: I'm having issues with Multipass currently, so the later part of the tutorial I
haven't been able to properly test to ensure that it works on a fresh VM

@s-makin s-makin changed the title Add new tutorial on managing software WIP: Add new tutorial on managing software Sep 26, 2024
Copy link
Collaborator

@YanisaHS YanisaHS left a comment

Choose a reason for hiding this comment

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

This tutorial is insane but also awesome!!! My review is done 🥵

("Approving" because I accidentally made this a formal review instead of just single comments ...)

tutorial/managing-software.md Outdated Show resolved Hide resolved
tutorial/managing-software.md Outdated Show resolved Hide resolved
tutorial/managing-software.md Outdated Show resolved Hide resolved
tutorial/managing-software.md Outdated Show resolved Hide resolved
Comment on lines 76 to 79
Your system software (and other deb packages) are handled through the
[Advanced Packaging Tool](https://ubuntu.com/server/docs/package-management#advanced-packaging-tool)
(APT). APT is a package *repository*; it contains both the **database** of the
packages available in Ubuntu, and it contains the **packages** themselves.
Copy link
Collaborator

Choose a reason for hiding this comment

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

You could make a comparison to pip here? Suggesting because that's a lot of people's first exposure to package management.

Or maybe you could be more clear and describe APT to those who have exposure to other package managers. I don't think the database part of your description makes it very clear what you're trying to emphasize. With apt, you can actually install full applications, whereas some package managers (such as pip) can only be used to install the packages, so apt is more powerful.

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

I'm not sure that pip use is extensive/widespread enough to make the comparison meaningful (especially because APT is the default in Ubuntu), but I can/should probably make the package management aspect more explicit. I'll have a fiddle and see what improvements I can make.

Comment on lines 1238 to 1240
Configuration is an important step, because this is where the Makefiles are
created that will allow us to install the package. It will take a few moments
as it checks all the files.
Copy link
Collaborator

Choose a reason for hiding this comment

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

The user is thrown into make/Makefiles here too. Can you provide context?

tutorial/managing-software.md Outdated Show resolved Hide resolved
tutorial/managing-software.md Outdated Show resolved Hide resolved
tutorial/managing-software.md Outdated Show resolved Hide resolved
tutorial/managing-software.md Outdated Show resolved Hide resolved
@s-makin s-makin changed the title WIP: Add new tutorial on managing software Add new tutorial on managing software Oct 14, 2024
@s-makin s-makin requested a review from cpaelzer October 14, 2024 17:18
Copy link
Contributor

@cpaelzer cpaelzer left a comment

Choose a reason for hiding this comment

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

Already quite good, I've left hopefully helpful suggestions.
But even more so at the end there was some content that I disagree (it should not be part of the tutorial).

tutorial/managing-software.rst Show resolved Hide resolved
tutorial/managing-software.rst Outdated Show resolved Hide resolved
tutorial/managing-software.rst Show resolved Hide resolved
tutorial/managing-software.rst Outdated Show resolved Hide resolved
tutorial/managing-software.rst Outdated Show resolved Hide resolved
tutorial/managing-software.rst Outdated Show resolved Hide resolved
tutorial/managing-software.rst Outdated Show resolved Hide resolved
tutorial/managing-software.rst Outdated Show resolved Hide resolved
tutorial/managing-software.rst Outdated Show resolved Hide resolved
* We know that our changes to conffiles are always safely preserved, while
changes to non-conffiles are reverted at the next upgrade or security fix.

* Importantly, we know how to verify checksums with ``md5sum`` or similar
Copy link
Contributor

Choose a reason for hiding this comment

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

You did not mention the build from source here, which is good - I do not want it here :-)

But this list also forgets about the install from a .deb file - which ok'ish.
I'm unsure if that should be here or also in a page of its own with big disclaimers (essentially the third party explanation we have).

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

I don't want to draw too much attention to it, since we prefer people don't do it and are only showing it as an FYI because we're doing it in a sandbox. Actually, now that I reflect more on the reasons to remove all the building from source stuff, I wonder if we should also remove the install from .deb stuff - but it does provide a convenient segue into snaps.

@s-makin s-makin merged commit d9c0c84 into canonical:main Oct 18, 2024
1 check passed
@s-makin s-makin deleted the new-tutorial branch October 18, 2024 08:01
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants