Update the docs after 3.1.1: Twig is required, the @OA note and the contributor workflow

Open
#164 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
3/5
Estimated time
1-2 days
Newbie friendliness
74/100
Issue type
Documentation
Clarity
Clearly specified
Activity status
Active
Tech stack
markdown, php
Domain
documentation

Research direction

Start with the listed Twig pages, v3.0/upgrade-guide.md, v3.0/cli/code-generation.md, and AGENTS.md; compare the 3.1.1 dependency and changelog details with the linked framework release. Then update the contributor workflow and check the edited internal links and anchors. Done means each Twig fact is stated once at its home page, the CLI note links to the upgrade guide, and the workflow describes staging and release pull requests as specified.

Written by the indexing model from the issue text.

Description

documentation

Summary

Three places in the docs repository do not match the released 3.1.1 and the way we work now.

Why

  1. Twig is a required dependency again (quantum-php/framework#626, in 3.1.1): twig/twig ^3.27 is in the framework's require, and RendererException::twigNotInstalled() and the adapter's "Twig is missing" check were removed. The pages still say Twig is optional and must be installed separately, so a reader is misled.
  2. The @OA note in the CLI guide is a long paragraph that repeats what the upgrade guide already explains.
  3. AGENTS.md still tells contributors to branch from master and open the pull request into master, while pages are written on a docs/<topic> branch from staging and published by a release pull request from staging into master.

Pages

  • Twig, v3.0/core-concepts/views.md (the paragraph that says Twig is "an optional renderer dependency"), v3.0/installation.md (twig/twig in the list of optional packages), v3.0/packages/renderer/overview.md (the "Twig support is optional" paragraph and the sentence about the adapter failing when Twig is not installed) and v3.0/packages/renderer/adapters.md: state that Twig comes with the framework, and drop the optional wording. Each fact is stated once at its home page and linked elsewhere.
  • Twig, v3.0/upgrade-guide.md: a short item in the 3.0 to 3.1 part: Twig is required again, composer update installs it, an application that pins an older Twig must allow ^3.27, and the removed RendererException::twigNotInstalled(). The 2.x to 3.0 note about 3.0.3 stays as it is, because it describes that release.
  • v3.0/cli/code-generation.md: shorten the @OA note to one sentence with a link to the OpenAPI item of the upgrade guide.
  • AGENTS.md, "Git Workflow": branch from staging, open the pull request into staging and link the ticket with Refs #n (a Closes line only works for a pull request into master), and publish with a release pull request from staging into master whose description has the closing keyword before every number (Closes #a, closes #b).

Acceptance criteria

  • every statement matches the framework code and changelog of 3.1.1
  • each fact is stated once at its home page and linked elsewhere
  • internal links and anchors resolve
  • the pull request goes into staging and is published with the next documentation release
Dominant language
No language data
Stars
3
Forks
1
Avg merge
2m
Merged PRs (30d)
26

Getting set up

This project ships no dev container, Dockerfile or contributing guide, so setting up is up to you: start from its README, and see our first-contribution guide for the general steps.

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from quantum-php/docs

All issues in quantum-php/docs

Similar issues

More Documentation issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.