[augustodsgv]

Discussed in #3424

Improves incus alias command help with args and numbered args examples
Improve sincus alias how-tos with args and numbered args
Refactors incus alias docs by creating a use case section and adding examples in the how-tos
Fixes sphinx automation by preventing colored terminal outputs that would break the docs
Fixes italic text with ref

[bensmrs]

@augustodsgv, you’ll want to make i18n and git add po, as you changed some translated strings.
Additionally, there are Markdown linting errors, which you can see with make doc-lint.

[augustodsgv]

@bensmrs thank you, I've missed that. Both fixed

[bensmrs]

Thanks. Please carefully read CONTRIBUTING.md, notably the “Commit structure” section, in order to properly name your commits messages. Please also rebase your commits so that commits that fix your own contribution disappear from the PR. That means that the changes in 3c4bf15 should directly be put into the commits that introduce the linting errors.
Sorry for the tedious process, but that really makes a difference when doing operations on the code such as git blame, by not polluting the history too much.

[augustodsgv]

@bensmrs no problem, I appreciate your patience. I've messed up my git timeline with the rebase, but it seems right now, my apologies. Do you think the new commit messages are fine, or is there something I can improve?

[bensmrs]

No problem. Rebasing is quite a common thing in this project, but it can take some time to get used to :)

Do you think the new commit messages are fine, or is there something I can improve?

So, re-reading your commit messages makes me realize that some of the guidelines in CONTRIBUTING.md are very wrong, we may wanna patch that, @stgraber…
cmd/alias should be incus/alias. doc/XXX is very inconsistent and we haven’t made any effort to try to change that, so that’s ok. Usually, changes to the Makefile are prefixed with Makefile:. Finally, the internationalization thingy should be on its own commit, as described in CONTRIBUTING.md (that one is correct 😄).
When in doubt, I have found useful to git blame the files I’m modifying and look at the commit messages for commits in 2025 and 2026, as they tend to follow some kind of good-enough discipline.

[bensmrs]

I’ll push on your branch to save you the trouble ;)

[augustodsgv]

Thanks for the corrections. Are these commit patterns something used by all (or most) OpenSource projects, or is it project specific?

[bensmrs]

It really depends. Some projects use so-called conventional commits, focused on the kind of change, then its scope. Some projects like Incus ditch the kind of change to only focus on its scope. Some projects go completely free-form, but that doesn’t really scale to many contributors and big code bases, in which cases you usually benefit from defining a few guidelines (and commit messages are a good start).

In any case, things are still pretty flexible in this project and you’ll find a fair bit of inconsistencies; it’s not great, but it’s not dramatic either :)

[stgraber]

Thanks!

[augustodsgv]

@bensmrs I'm more used to the conventional commits, that's what I use at work, but it's nice to learn new patterns. I'm excited to learn the Incus conventions by submitting new changes, thanks for your help :)

[augustodsgv]

I just noticed that there is an error in the command help I modified, where the example command uses the Incus command instead of incus.

Incus alias add volume "storage volume @ARGS@"
    Create a short command for managing volumes

In this case, should I open a PR adding a fix commit or should I rebase the commit that introduced this error?