docs: Incorporate UX feedback into 12-factor tutorials
Metadata
Current evaluation
Merged as 9a40a4a3, updating 12-factor tutorials with clearer skopeo guidance, file headers, and corrected Express and Spring Boot setup instructions.
Resolution: closed resolved
Reason: PR canonical/rockcraft#893 was approved and merged as commit 9a40a4a3 after all required CI checks passed.
Evaluated by: mr-cal-bot
No scores available.
Issue body
- [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 ran `make lint` and received errors on files this PR doesn't touch.
---
Updates to the tutorials based on feedback in UX sessions:
1. When copying the skopeo command for the chiseled hello world rock. The user missed the hint to change the name in the project file to `0.1-chisel`, resulting in a error.
2. File headers could be added to file excerpts (app.py) [External example](https://www.digitalocean.com/community/tutorials/how-to-make-a-web-application-using-flask-in-python-3)
3. Clarification may be needed on what the skopeo command is doing. Maybe we could also mention about how Docker requires rocks (or images in general) to be imported into the daemon since they cannot be executed directly like an executable.
In addition, two corrections to the Express and Spring Boot tutorials:
1. Add `mkdir <app rock name>` and `cd <app rock name>` to the beginning of the tutorial so that the rock will have the correct name from the start.
2. Update the port to the correct value.
Evaluation history
| Date | Model | Scores | Action | Summary |
|---|---|---|---|---|
| stealth/space-bunny-alpha | — | closed resolved | Merged as 9a40a4a3, updating 12-factor tutorials with clearer skopeo guidance, file headers, and corrected Express and Spring Boot setup instructions. | |
| stealth/space-bunny-alpha | — | closed resolved | Merged UX-driven updates to the 12-factor tutorials, clarifying skopeo usage and file excerpts and correcting Express and Spring Boot setup instructions. | |
| qwen/qwen3.6-35b-a3b | — | — | Merged documentation updates incorporating UX feedback into 12-factor tutorials. Changes clarify skopeo usage, add file headers, correct Express and Spring Boot steps, and fix port values. All CI checks passed and reviewers approved the changes. | |
| qwen3.6-35b-a3b-mtp-q6 | — | — | Merged documentation updates to 12-factor tutorials incorporating UX feedback, command clarifications, and tutorial corrections. Unrelated CI test failures were rerun and resolved prior to final merge. |
Update history
No update history recorded yet.
Related issues
| Issue | Project | State | Summary | Similarity |
|---|---|---|---|---|
| #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. | |
| #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). | |
| #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. | |
| #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. | |
| #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. | |
| #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. | |
| #956 docs: Incorporate UX feedback into 12-factor tutorials | rockcraft | merged | 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. | |
| #2085 docs: update 12-factor tutorials | charmcraft | merged | Merged in #2085 (79fa5ad9), updating 12-factor tutorials to rST, incorporating UX feedback, and standardizing content after #2083. | |
| #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. | |
| #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. |