← Back to issue list

docs: Incorporate UX feedback into 12-factor tutorials

View original Github issue

Metadata

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

Current evaluation

Docs-only PR merged as commit c28f1197:12-factor tutorials updated with UX feedback — corrected browser visit instructions, Express 'cd ..' moved into the init rock block, FastAPI experimental extension env var, expanded Next steps, and intersphinx links in conf.py.

Resolution: closed resolved

Reason: The PR itself was merged into main as commit c28f1197 ('docs: Incorporate UX feedback into 12-factor tutorials (#956)'), touching 9 files (+228/-22). The only failing check, snap-tests, is unrelated to these documentation-only changes.

Evaluated by: mr-cal-bot

No scores available.

Issue body

Incorporate feedback from UX sessions into the 12-factor tutorials. ### Summary of changes * Django and Express tutorials: The note about visiting the app in a browser was incorrect. This PR updates the notes to provide the correct instructions for visiting the app in a browser. I tested the instructions to verify that they work for my setup. * Express tutorial: A participant noted that the `cd ..` command before initializing the rock was easily missed and caused issues for them during the session. This PR moves the command into the same code block that initializes the rock. * FastAPI tutorial: Export `ROCKCRAFT_ENABLE_EXPERIMENTAL_EXTENSIONS` as an environment variable, identical to the other tutorials showcasing experimental extensions. * All tutorials: Add or update the "Next steps" section to provide more relevant and useful links for the user looking for next steps, more information behind the extension or rocks, and to understand the "why" behind the 12-factor tooling. * `conf.py`: Add intersphinx for the Charmcraft and 12-factor links in the "Next steps" sections of the tutorials. - [X] Have you followed the guidelines for contributing? - [X] Have you signed the [CLA](http://www.ubuntu.com/legal/contributors/)? - [ ] Have you successfully run `make lint && make test`? --- I successfully ran `make lint-docs` before opening this PR.

Evaluation history

Date Model Scores Action Summary
stealth/space-bunny-alpha — closed resolved Docs-only PR merged as commit c28f1197:12-factor tutorials updated with UX feedback — corrected browser visit instructions, Express 'cd ..' moved into the init rock block, FastAPI experimental extension env var, expanded Next steps, and intersphinx links in conf.py.
stealth/space-bunny-alpha — closed resolved Merged as c28f1197: updated 12-factor tutorials with corrected browser instructions, clearer Express setup, FastAPI experimental flags, improved next steps, and intersphinx links.
qwen/qwen3.6-35b-a3b — — Merged documentation updates to 12-factor tutorials incorporating UX feedback. Corrects browser instructions, reorganizes commands, adds experimental extension variables, updates next steps, and adds intersphinx links. Approved by two reviewers and passed CI.
qwen3.6-35b-a3b-mtp-q6 — — Merged updates to 12-factor tutorials based on UX feedback. Fixes browser navigation instructions, reorganizes terminal commands, adds experimental extension environment variables, improves next steps links, and adds intersphinx references.

Update history

No update history recorded yet.

Related work

  • Related To: canonical/rockcraft#893 (confidence 90%)

    Earlier PR in the same recurring 'Incorporate UX feedback into 12-factor tutorials' docs series (commit 9a40a4a3).

  • Related To: canonical/rockcraft#918 (confidence 90%)

    Follow-up PR in the same docs series, merged as ddb5bbba, covering further UX feedback items.

  • Related To: canonical/rockcraft#1006 (confidence 90%)

    Further follow-up in the same series, merged as 9aec04c7, addressing remaining UX feedback points.

Related issues

Issue Project State Summary Similarity
#2425 docs: Incorporate UX feedback into 12-factor tutorials charmcraft merged Merged docs PR applying UX-session feedback to the 12-factor tutorials (commit 17ce91b5, 8 files, +349/-207): reordered rockcraft.yaml arch steps, reworded rock upload, code-blocked curl/config commands, and refreshed next-step links.
89%
#2455 docs: Incorporate UX feedback into 12-factor tutorials charmcraft merged Docs-only PR merged to main as commit d31736f1, applying UX-session feedback (ISD-4286) to the 12-factor tutorials: reworded the project-directory cleanup step, removed explicit cd commands, and moved code-block comments into prose.
88%
#2387 docs: Incorporate UX feedback into 12-factor tutorials charmcraft merged Docs-only PR merged (commit 6368b845): applied UX session feedback to the 12-factor tutorials — added Deploy intro, Verify/Destroy app steps, an achievements section, and a PostgreSQL spelling fix (+125/-81, 5 files).
87%
#2445 docs: Incorporate UX feedback into 12-factor tutorials charmcraft merged Merged PR #2445 as commit 787f82c4, updating six 12-factor tutorial files with UX feedback on resources, ingress, configuration, wording, and PostgreSQL setup.
86%
#918 docs: Incorporate UX feedback into 12-factor tutorials rockcraft merged Merged PR #918 as ddb5bbba, updating the 12-factor tutorials with UX feedback on architecture, setup, Multipass, multi-architecture commands, pack warnings, and terminology.
86%
#893 docs: Incorporate UX feedback into 12-factor tutorials rockcraft merged Merged as 9a40a4a3, updating 12-factor tutorials with clearer skopeo guidance, file headers, and corrected Express and Spring Boot setup instructions.
84%
#2354 docs: Incorporate UX feedback into 12-factor tutorials charmcraft merged Merged UX-driven updates to the 12-factor tutorials: dropdown code snippets, explicit paths, and clearer MicroK8s and Juju setup commands.
84%
#2463 docs: Incorporate UX feedback into 12-factor tutorials charmcraft merged Merged PR #2463 updated 12-factor tutorials with experimental-channel guidance, reordered LXD setup, and clarified that subsequent commands run inside the VM.
81%
#1006 docs: Incorporate UX feedback into 12-factor tutorials rockcraft merged Merged PR #1006 in commit 9aec04c7, clarifying VM command context, terminal shutdown, and rockcraft pack overwriting when rock versions are unchanged.
77%
#1253 docs: Incorporate user feedback in the 12-factor reference pages rockcraft merged Docs PR #1253 merged as commit 176cba44 into rockcraft main, applying UXR feedback to 12-factor reference pages (headings, parts snippets, include/exclude guidance, captions, acronym clarifications).
76%