← Back to issue list

docs: refactor tutorial

View original Github issue

Metadata

Project
rockcraft
Number
#855
Type
pull request
State
open
Author
alesancor1
Labels
—
Created
Updated
Closed
—

Current evaluation

Docs refactor merging tutorials into a single NGINX static-site tutorial and reclassifying 12-factor/PyPI/node tutorials as how-to guides (76 files, +1291/-540). Open, changes requested, dormant 413 days; main docs tree has since evolved without it.

Suggested action: close stale

Reason: cjdcordeiro explicitly told the author 'Feel free to hold this PR until the next sprint, and pls do invite us to take part in such discussions', and warned the 12-factor tutorials 'have already been referenced elsewhere (blogs, etc.) without pinning a specific version of the docs'; the author never replied and there has been no activity in 413 days. The branch has also diverged from HEAD, where docs/index.rst and docs/tutorial/index.rst still list nine tutorials under the tutorial quadrant and later merged work went the other way (e.g. merged #1002 'maintain the tutorial quadrant', #1006/#956/#918 UX feedback on the 12-factor tutorials in place, and #1222 removing a tutorial), so a 76-file rebase of this scope is unlikely to apply cleanly. Only snap-tests is failing on an otherwise green check set, but the blocker is an unmade product decision (ROCKS-1275), not code; close as stale and reopen as a fresh branch once the Engineering Sprint outcome is recorded.

Evaluated by: mr-cal-bot

Impact: 32 Quick Win: 3 Complexity: 55 Confidence: 74 Actionability: 18

Issue body

- [x] Have you followed the guidelines for contributing? - [x] Have you signed the [CLA](http://www.ubuntu.com/legal/contributors/)? - [x] Have you successfully run `make lint && make test`? --- This PR presents a new tutorial that covers the creation of a rock serving a static HTML file with NGINX via HTTP(s). ## **Rationale** From @medubelko: > The tutorial should be a singular, opinionated, end-to-end learning experience with a definite outcome. We’ve already achieved the latter goals in the Hello World page, but by introducing additional tutorial outcomes – for chisel, for Flask, and so forth – we’ve undermined the first two goals. The outcome is to containerise something useful, which means outside software. But the tutorial shouldn’t retread ground and cover multiple similar outcomes, making them compete with each other Additionally, the toc-tree from how-to guides has been grouped, since the old tutorials have been moved there, and there were many guides, making it hard to navigate. --- Other PRs affected by these changes: * https://github.com/canonical/rockcraft/pull/847 - modifies `/tutorial/node-app.rst` which has been moved to `how-to/rocks/pack-rocks` * https://github.com/canonical/rockcraft/pull/846 - should be closed if this is merged. New tutorial already include this. * https://github.com/canonical/rockcraft/pull/836 - changes should be made to the tutorials on the new location * https://github.com/canonical/rockcraft/pull/828 - changes should be made to the tutorials on the new location --- See [built-docs](https://canonical-ubuntu-documentation-library--855.com.readthedocs.build/rockcraft/en/855/)

Evaluation history

Date Model Scores Action Summary
stealth/space-bunny-alpha
Impact: 32
Quick Win: 3
Complexity: 55
Confidence: 74
Actionability: 18
close stale Docs refactor merging tutorials into a single NGINX static-site tutorial and reclassifying 12-factor/PyPI/node tutorials as how-to guides (76 files, +1291/-540). Open, changes requested, dormant 413 days; main docs tree has since evolved without it.
qwen/qwen3.6-35b-a3b
Impact: 35
Quick Win: 5
Complexity: 45
Confidence: 65
Actionability: 25
keep open Documentation PR refactoring tutorials into how-to guides. Under review with changes requested. CI has failing snap-tests. Blocked by ongoing documentation strategy discussions.
qwen/qwen3.8-27b
Impact: 35
Quick Win: 10
Staleness: 88
Complexity: 72
Confidence: 78
close stale Docs refactor moving tutorials to how-to guides and adding NGINX static HTML tutorial. 76 files changed. Review status changes_requested; maintainer said approach was 'perhaps not in this way' and to hold. Docs since reorganized separately, superseding this PR's structure.
qwen/qwen3.6-35b-a3b
Staleness: 75
Complexity: 15
Confidence: 90
keep open Refactors documentation by consolidating tutorials and moving framework guides to how-to sections. Currently on hold pending internal sprint discussions to finalize structure and terminology.
qwen3.6-35b-a3b-mtp-q6
Staleness: 35
Complexity: 45
Confidence: 90
keep open Refactors documentation to consolidate tutorials into a single end-to-end guide and moves older tutorials to how-to sections. Currently on hold pending architectural decisions and stakeholder alignment on documentation structure.
qwen3.6-35b-a3b-mtp-q6
Staleness: 85
Complexity: 25
Confidence: 75
close stale Refactors tutorial structure by consolidating content into a single end-to-end guide and moving legacy tutorials to how-to sections. Currently inactive for over a year after being explicitly shelved pending sprint planning.

Update history

No update history recorded yet.

Related work

  • Related To: canonical/rockcraft#1002 (confidence 82%)

    Merged later (#1340-era docs work, commit 9138c835) and maintained the tutorial quadrant as it exists today, i.e. landing after and against this PR's reclassification of 12-factor tutorials to how-to.

  • Related To: canonical/rockcraft#846 (confidence 55%)

    Cited in the PR body as one that should be closed if this merges; still open and itself stale, and its actual title (rootless rock how-to) no longer matches the node-app tutorial the body describes.

  • Related To: canonical/rockcraft#836 (confidence 45%)

    Cited in the body as needing reapplication on the new location; also open and inactive, so both PRs depend on the same unmade restructuring decision.

Related issues

No related issues found above the similarity threshold.