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

Suggested action: close stale

Reason: Maintainer @cjdcordeiro stated the approach was 'perhaps not in this way' and advised holding until sprint discussion. Since then (381 days), the docs were reorganized separately: 12-factor how-to guides reorganized in #877, tutorial quadrant maintained in #1002, and numerous individual tutorial updates merged. The PR's core proposal (moving tutorials to how-to, NGINX static HTML tutorial) was not adopted, and the review remains in changes_requested with no author follow-up.

Impact: 35 Quick Win: 9.8 Staleness: 88 Complexity: 72 Confidence: 78

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
qwen/qwen3.8-27b
Impact: 35
Quick Win: 9.8
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.
qwen3.6-35b-a3b-mtp-q6
Staleness: 75
Complexity: 20
Confidence: 90
keep open Refactors the documentation tutorial into a single end-to-end guide, moving legacy examples to how-to sections. Currently on hold pending sprint planning to resolve Diataxis alignment and 12-factor tutorial structure concerns.

Update history

No update history recorded yet.

Related work

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

    Reorganized 12-factor how-to guides separately, addressing part of this PR's restructuring goal in a different way

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

    Maintained the tutorial quadrant, indicating the existing tutorial structure was kept rather than merged into how-to as this PR proposed

Related issues

No related issues found above the similarity threshold.