← Back to issue list

docs: Incorporate user feedback in the 12-factor reference pages

View original Github issue

Metadata

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

Current evaluation

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).

Resolution: closed resolved

Reason: The PR itself was merged into main as commit 176cba44 ("docs: Incorporate user feedback in the 12-factor reference pages (#1253)"), with 2 approving reviews and all CI checks passing; author confirmed remaining review threads were addressed and medubelko said it was good to merge.

Evaluated by: mr-cal-bot

No scores available.

Issue body

This PR updates the 12-factor reference pages to incorporate the following feedback received during UXR sessions: * Update the headers so that they’re human-readable and indicate the purpose or goal of the section * Clarify that the `parts` snippets are technically optional, but depending on the complexity of the project, could be required. Clarify when the user needs to add the snippet versus when they can safely ignore the snippet * Clarify the parts snippets that include or exclude files. Add this type of snippet overrides the default, and you exclude a file by including the snippet in your project file without the file. Add a reference for more complex ways of including or excluding files (e.g., with glob patterns) * Add more links (start script in the Express framework page, bare base, rocks, etc.) * Add captions to all code snippets so it’s clear that they touch the rockcraft.yaml project file. * Double check and clarify any undefined acronyms (e.g. WSGI in the Flask reference page). I successfully ran `make docs-lint` before opening the PR. I also did not add meta descriptions to avoid conflicts with https://github.com/canonical/rockcraft/pull/1246 --- - [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/). - [x] I've successfully run `make lint && make test`. - [x] I've added or updated any relevant documentation. - [ ] In documents I changed, I [added a meta description](https://canonical-starflow.readthedocs-hosted.com/how-to/add-a-page-meta-description/) if one was missing. - [ ] I've updated the relevant release notes.

Evaluation history

Date Model Scores Action Summary
stealth/space-bunny-alpha — closed resolved 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).
stealth/space-bunny-alpha — closed resolved Merged PR #1253 (commit 176cba44) by external contributor erinecon, applying UXR user feedback to the 12-factor reference pages: clearer headings, parts/file include-exclude guidance, code captions and acronym fixes.
stealth/space-bunny-alpha — closed resolved Merged in canonical/rockcraft#1253 (176cba44), improving 12-factor reference headings, parts/file guidance, links, code captions, and acronym clarity.
qwen/qwen3.6-35b-a3b — — Merged documentation updates to the 12-factor reference pages. Incorporates UXR feedback by improving headers, clarifying parts snippets and file inclusion rules, adding links and captions, and fixing acronyms. Approved and passed CI.
qwen3.6-35b-a3b-mtp-q6 — — Merged documentation updates to the 12-factor reference pages. Changes include human-readable headers, clarified parts snippet usage, file inclusion guidance, added framework links. Feedback addressed and lint passed before merge.

Update history

No update history recorded yet.

Related work

  • Related To: canonical/rockcraft#1246 (confidence 70%)

    PR author deliberately skipped adding meta descriptions to avoid conflicting with concurrent PR #1246.

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.
83%
#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.
78%
#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.
77%
#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.
76%
#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).
76%
#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.
75%
#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.
75%
#2282 docs: Updates to the 12-factor tutorials charmcraft merged Merged PR #2282 as commit 2199bc08, updating four 12-factor tutorials with Rockcraft context, expanded Skopeo guidance, and clearer MicroK8s registry wording.
74%
#2276 docs: Updates to the 12-factor tutorials charmcraft merged Docs-only PR merged as commit 5cacee4a, applying six updates from issue #2235 across all four 12-factor tutorials: rock/Juju model intros, 'edit' vs 'open' wording, a charmcraft pack seealso box, and Django notes.
72%
#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.
72%