docs: Add documentation for new BASH syntax

[sergio-costas]

Since snapd 2.77 onward, support for BASH syntax ${VAR:+value} and ${VAR:-default} is available for environment variable values. This patch adds it to the documentation, to ensure that it will be explained in the docs web pages.

---

• I've followed the contribution guidelines.
• I've signed the CLA.
• I've successfully run make lint && make test.
• I've added or updated any relevant documentation.
• In documents I changed, I added a meta description if one was missing.
• I've updated the relevant release notes.

[mr-cal]

Thanks, @sergio-costas !

I've put my suggestion in and am also requesting a review from @canonical/starcraft-authors.

[Copilot]

Pull request overview

Adds documentation to the environment field schema/docs explaining that snapd (>= 2.77) supports Bash parameter expansion in environment variable values, and how to gate usage via assumes.

Changes:

• Document support for ${VAR:+value} and ${VAR:-default} in environment variable values (snapd 2.77+).
• Clarify limitations (no nested parameter expansion) and provide examples.
• Recommend using assumes: [snapd2.77] to require the needed snapd feature level.

[medubelko]

Thanks @sergio-costas!

I went deep in trying to make this easier for users to parse. Let me know what you think!

[medubelko]

Here's my attempt to make it a little more digestible:

Suggested change

	From snapd 2.77 onward, support for BASH syntax ``${VAR:+value}`` and
	``${VAR:-default}`` is available for environment variable values. Also
	``${VAR:+$OTHER_VAR}`` and ``${VAR:-$OTHER_VAR}`` are supported, but internal
	braces are not supported (so , for example, ``${VAR:+${OTHER_VAR}}`` won't work).
	With SnapD 2.77 and higher, this key supports Bash parameter expansions:
	- Override the current value with ``${VAR:+override}``
	- Fall back to a value with ``${VAR:-fallback}``
	- Copy another variable's value with ``${VAR:+$OTHER_VAR}``
	- Fall back to another variable's value with ``${VAR:-$OTHER_VAR}``
	Nested braces such as ``${VAR:+${OTHER_VAR}}`` aren't supported.

[sergio-costas]

Looks much better, but I still see it a little bit complex... Maybe adding some examples would help?

[medubelko]

Suggested change

	To ensure this feature is available, use the ``assumes`` key to require a
	minimum version of snapd, for example ``assumes: [snapd2.77]``.
	For parameter expansion, the ``assumes`` key must be set to a
	minimum version of SnapD, such as ``[snapd2.77]``.

[sergio-costas]

Maybe... "If parameter expansion is used, it is paramount to set the assumes key to version 2.77 or later (such as assumes: [snapd2.77])".

[bepri]

I think the word "paramount" feels a little too glittery. I don't like the "such as" in Michael's suggestion either, because it feels a suggestion that you can pin it to whatever version you want, so long as you're pinning it at all.

How about:

Suggested change

	To ensure this feature is available, use the ``assumes`` key to require a
	minimum version of snapd, for example ``assumes: [snapd2.77]``.
	Since this feature requires a minimum version of SnapD, use the ``assumes`` key to
	constrain your snap to a supported SnapD version with ``assumes: [snapd2.77]``.