← Back to issue list

docs: Update LXD/Docker warning block in 12-factor tutorials

View original Github issue

Metadata

Project
rockcraft
Number
#1061
Type
pull request
State
merged
Author
erinecon
Labels
Created
Updated
Closed

Current evaluation

Merged update clarifying LXD/Docker connectivity workarounds in 12-factor tutorials. Changes reposition network bridge instructions, add an environment variable for bridge names, and include sudo. Approved by three reviewers and merged.

Suggested action:

No scores available.

Issue body

During a UX session, a participant required the workaround in the 12-factor Flask tutorial to fix the connectivity issue between Docker and LXD. The experience had some tension that can be resolved with documentation changes. The following updates were made to the warning blocks in all 12-factor tutorials: * The user needs to know the name of the network bridge before running the commands, so this instruction was moved earlier in the block. * The code block contains four commands that all require the name of the network bridge, so the block now instructs the user to save the name of their network bridge to an environment variable before running the fix. The environment variable is now used in the code block instead of a placeholder variable. * Added `sudo` to all commands (required to run the commands, and should be safe since the tutorial takes place within a Multipass VM). Ideally, a code block that can dynamically update with the name of the user's network bridge would be best. However, this solution would require custom JS code, and I didn't want to make this RTD project more complex when an environment variable can achieve the same result. --- - [X] I've followed the [contribution guidelines](https://github.com/canonical/rockcraft/blob/main/CONTRIBUTING.md). - [X] I've signed the [CLA](http://www.ubuntu.com/legal/contributors/). - [ ] I've successfully run `make lint && make test`. - [X] I've added or updated any relevant documentation. I ran `make lint-docs` locally and fixed the issues.

Evaluation history

Date Model Scores Action Summary
qwen/qwen3.6-35b-a3b Merged update clarifying LXD/Docker connectivity workarounds in 12-factor tutorials. Changes reposition network bridge instructions, add an environment variable for bridge names, and include sudo. Approved by three reviewers and merged.
qwen3.6-35b-a3b-mtp-q6 Merged documentation updates for 12-factor tutorials clarifying the LXD/Docker connectivity workaround. Updates move the network bridge instruction earlier, replace placeholders with an environment variable, and add sudo to commands based on UX feedback.
qwen3.6-35b-a3b-mtp-q6 Merged documentation updates for LXD/Docker connectivity workarounds in 12-factor tutorials. Changes move network bridge instructions earlier, replace placeholders with an environment variable, and add sudo to commands to resolve UX friction.

Update history

No update history recorded yet.

Related issues

Issue Project State Summary Similarity
#1148 docs: update LXD/Docker incompatibility handling rockcraft merged Merged documentation update adding LXD/Docker connectivity workaround and firewall warning to shared setup instructions. Iteratively resolved CI failures, docs build errors, and stale intersphinx mappings before final merge. Closes #1144.
79%
#2463 docs: Incorporate UX feedback into 12-factor tutorials charmcraft merged Merged documentation update incorporating UX feedback into 12-factor tutorials. Changes add an experimental extensions warning, restructure LXD setup steps, and clarify VM shell context. Approved by two reviewers and passed CI checks.
75%
#1144 docs: Update handling of LXD/Docker incompatibility rockcraft closed Documentation updates for LXD/Docker incompatibility were implemented in PR #1148. The issue was closed as superseded by the merged pull request, which added sysctl configuration steps, linked official LXD docs, and updated warning admonitions.
74%