Streamline build-packages-locally article

[BAMF0]

Description

This pull request will streamline the article "How to build packages locally" by making it propose one recommended and more authoritative way of building packages using sbuild, rather than multiple. It is needed to provide a more up to date and direct instruction set that should allow contributor's to build packages in a more uniform way.

---

Related issue

• Fixes: Streamline 'local build' instructions #318

---

Checklist

• I have read and followed the Ubuntu Project contributing guide
• My pull request is linked to an existing issue (if applicable)
• I have tested my changes, and they work as expected

---

Additional notes (optional)

Configuration files as code blocks do not allow copying hashes ("#"), which is currently a UX bug since the text has to be manually copied instead.

[BAMF0]

Force pushed for typo correction

[rkratky]

Thank you, @BAMF0! I wanted to suggest a bit more involved formatting changes, so I submitted my review in the form of a PR against your branch at BAMF0#1

[BAMF0]

@rkratky Nice, thanks! I appreciate the changes. Let me have a look.

[BAMF0]

Merged your changes now, the looked good to me.

[jbicha]

You need to fix #270 if you're going to recommend unshare and ~/.config/sbuild/sbuild.pl` since otherwise the instructions won't work with the current Ubuntu LTS.

See my notes from #295

I don't think enabling experimental tags (-E) is useful for beginners. Lintian already complains about too many things (which is slowly being improved), so we shouldn't add additional warnings that the Lintian maintainers don't recommend and aren't needed even for main inclusion review.

The purge config is unnecessary for unshare, but it is helpful if you're going to use schroot for cross building.

$build_dir = '/home/my_user/schroot/build';
$log_dir = '/home/my_user/schroot/logs';

I don't think this should mention schroot. In my testing, I noticed that the log directory must exist for sbuild to store logs there.

[BAMF0]

@jbicha Great points! Thanks for the feedback. It's really easy to assume everything from the perspective of the bleeding edge release, however that also risks these incompatibilities you mentioned here.

In this case, I think the way forward is fixing #270 as you suggested, saying in build-packages-locally.rst that the unshare backend requires 25.10 or later (as 25.04 is EOL), and making a note that it can also be used on 24.04 LTS but only if noble-backports is added to the apt sources.

[mwhudson]

Here's a few unsolicited comments! I think the changes mostly go in the right direction but some things are a bit muddled. It probably makes sense to document the new shiny unshare backend and then have a section that says "on older releases set up schroot like a b c"? (I think it's just a touch premature to drop all documentation of the schroot based solution).

[paride]

With this ~/.config/sbuild/config.pl I can just sbuild or sbuild -d <release> most of the time, and it just works:

$chroot_mode = 'unshare';
$unshare_mmdebstrap_keep_tarball = 1;

# /tmp is tmpfs and large builds will fail after filling all memory.
$unshare_tmpdir_template = '/var/tmp/tmp.sbuild.XXXXXXXXXX';

$clean_source = 0;
$run_lintian = 0;

[rkratky]

Thank you, @BAMF0. A few more suggestions.

[BAMF0]

Hey folks! In order to get things moving, we are planning to get this merged and move the current unresolved comments into a separate issue in order to keep track of them. I will link the new issue here once it has been created.

[BAMF0]

Here is the new issue: #536

For ease of use, I have linked the unresolved comments as well in there.

[rkratky]

Thanks!

[jugmac00]

Hey @rkratky, hey @BAMF0,

I was trying to follow the docs a week before this got merged,and wanted to help improving the docs myself, but now I see this already have been merged. Thanks for that.

There is one thing I'd like to quickly discuss.

We have a dedicated section about setting up chroots in https://documentation.ubuntu.com/project/contributors/setup/set-up-for-ubuntu-development/#sbuild, but still this PR duplicated some information into the sbuild section of https://documentation.ubuntu.com/project/contributors/bug-fix/build-packages-locally/#setting-up-sbuild.

Is this done on purpose? Or would it be better to have a single source of truth and just link to it?

Cheers!

[BAMF0]

Is this done on purpose? Or would it be better to have a single source of truth and just link to it?

Hey there @jugmac00! That was interestingly something me and Robert discussed. The reason for duplicating the information there was essentially to provide a coherent guide for building packages, and it was believed that linking to a section of another article would disrupt the flow (seeing as the article in this PR specifically deals with using sbuild).

I think having a single source of truth would be the best way to go about it, although I'm not certain where to put it. I think the "How to set up for Ubuntu development" is a very concise place for configuration settings, however it does not contain any usage examples relating to the tools it configures. Consider an entirely new contributor reading that article - I'd wager they would have questions like "what is sbuild?", "what is it used for?", or "why do we use this setting?". Putting such information in a more dedicated article related to the tool's purpose would probably help answering these questions better.

What do you think?

[jugmac00]

@BAMF0 I think having a single place which we can refer to is the best option.

I also still think we can everything in a "How to set up for Ubuntu development" and add a few more hints about what these tools are about, maybe in a collapsed view.

I was an entirely new contributor like 2 weeks ago when I tried it for the first time - and I would have not minded a "please set up your dev environment first before you read on" article. As we both know, there was nothing there two weeks ago :)

I discussed this with @cpaelzer and he will clarify the direction with the TAs.

I have a couple of more ideas on how to improve that page, but will wait for a decision.

[BAMF0]

I also still think we can everything in a "How to set up for Ubuntu development" and add a few more hints about what these tools are about, maybe in a collapsed view.

+1 I think that's a good suggestion. Having a "Step 0"/Prologue that should be completed before these guides is something we should go for. In that case each article author could always write with the assumption that the reader at least has their environment setup.

Now that you bring it up it's likely better to revise https://documentation.ubuntu.com/project/contributors/setup/set-up-for-ubuntu-development/, than to split up or move that information.

[jugmac00]

https://documentation.ubuntu.com/project/contributors/setup/set-up-for-ubuntu-development/ has been improved already, at least about what packages need to be installed, thanks to @cpaelzer

I still propose to move all schroot setup related info to a single location, and ideally to that page, too.

Is this something we can agree upon? Or do you or @rkratky insist on having things duplicated in build-packages-locally.rst?

I just want to make sure I know where I can put my focus on - there are many other places to improve our docs.

[BAMF0]

I'm for moving it into a single location. In that case I would link to https://documentation.ubuntu.com/project/contributors/setup/set-up-for-ubuntu-development/ as a prerequisite for the entire article. It will probably be a bit slim, but that's maybe okay in that case.

If we move it, I think we should consider having a structure similar to build-packages-locally.rst for the setting up sbuild part. The main problem I see with the current setup is that it is not very authoritative. For instance, if available the unshare back-end is what should be used over shcroot, however right now that is only listed as a note. This makes the section a bit unfocused as well.

I would like to know @rkratky's opinion as well, but besides that I'm for your proposal.

[rkratky]

Hi @jugmac00, @BAMF0. I agree with what's being proposed. My hesitation before stemmed mainly from the fact that the 'set up for U. development' page used to be a mess. It's better now.

I think we should still improve it and make it shorter + more opinionated/authoritative. But overall, I support having it as a prerequisite for all the other build, fix, etc. articles.

[jugmac00]

@BAMF0 Is this something you want to work on? i.e. as a first step unify the sbuild setup in https://documentation.ubuntu.com/project/contributors/setup/set-up-for-ubuntu-development/?

I have a couple of notes, and I would love to iterate with you on the PR.

Also, what do you think of using tabs to show ways for setting this up until 24.04 and a default tab to show what is the way with newer versions?

For a visual example of tabs in docs (with unrelated content), see https://canonical-launchpad-admin-manual--261.com.readthedocs.build/en/261/reference/read-launchpad-logs-via-rsync/#known-rsync-modules.

[BAMF0]

@jugmac00 Absolutely, I'd gladly work on it!

I think tabs seem like a good idea. It gives a good overview of the different versions of similar instructions. We should try that out and see how it feels.

Perhaps I could start by creating an issue named something like "Centralize and overhaul sbuild setup instructions"?

[jugmac00]

Sounds great!

[BAMF0]

For reference: #572