symfony/symfony-docs: a 6.4 pull request base on a 7.4 default branch

A manual under version control, not a website maintained by hand

The problem here is narrow and worth stating without inflation. The Symfony reference is not a set of pages edited in place on a web server, it is a tree of reStructuredText files kept in version control, and every wording change travels through a pull request. The repository's topic tags read docs, hacktoberfest, php and symfony, and its homepage is https://symfony.com/doc, so the audience splits cleanly in two.

The first group is the people who write the manual: contributors who fix a wrong class name, document a missing config key or describe a feature that has just shipped. They need a review path and a way to see the rendered result before it goes out. The second group is much smaller, developers who want the whole manual on a machine with no connection, or who are chasing an example that renders wrong and need to read it as a reader will.

What the tree does not hold matters as much as what it does. There is no framework source, no test suite for application code and no installer for the components the pages describe. Inside the repository, PHP exists only to render text. A contributor who clones expecting the framework finds a documentation build, and the pull request note about 6.4 is the first sign that the versioning here is manual rather than automated.

composer install runs inside _build, not at the repository root

The build is four commands, and the order matters more than it looks. The README frames this step as unnecessary for contributing and useful for debugging a docs problem or reading offline, then puts the dependency install inside the builder directory instead of the repository root:

$ git clone [email protected]:symfony/symfony-docs.git

$ cd symfony-docs/
$ cd _build/

$ composer install

$ php build.php

Read the two directory changes in sequence. `composer install` runs from `_build/`, so the builder carries its own dependency set rather than sharing one declared at the root, and `php build.php` is executed from the same place and writes the rendered pages into `output/`. Nothing in the tree describes a root composer.json, which is why the path changes before the install instead of after it.

After the build, the PHP built-in server is enough to read the result, and it serves the generated directory rather than the source tree:

$ php -S localhost:8000 -t output/

Open `http://localhost:8000` and you are reading generated pages, not the published site. What the README leaves open is the floor: it names no PHP version requirement, no build time and no list of pages, so take none of those from this page and check what your own environment loads before you promise anyone a working local copy.

Windows gets a WSL detour because the builder refuses it

The application that builds these docs does not support Windows, and the README says so in a note rather than inside the command list. Stated workaround: a Linux distribution under WSL, which makes the four commands above a Linux and macOS sequence rather than a universal one.

That constraint decides who can do what. A Windows contributor can still open a pull request against 6.4 without touching the builder, because the contribution path runs through the contributing guide at https://symfony.com/doc/current/contributing/documentation/overview.html and the README treats the local build as optional. What a Windows user cannot do without a Linux environment is reproduce a rendering problem, and a rendering problem is the entire reason the build exists.

That split caps debugging for everyone else. With the build you can read a page before it ships and see the output the site will serve. Without it you are reading the published manual, where a fix means waiting for a publish and hoping the build behaves the same way it will on the server.

The pull request base is 6.4 while the default branch is 7.4

Put the branch setting next to the contributing note and three Symfony versions end up in one repository. The default branch is 7.4. The instruction marked IMPORTANT asks for 6.4 as the base of your pull requests unless you are documenting a feature introduced after Symfony 6.4, with Symfony 7.2 offered as the example. The online manual answers to a URL ending in current.

So a fresh clone hands you 7.4 while the instruction asks for 6.4, and a contributor who opens a pull request from whatever branch the clone produced has picked the base the note steers away from. The exception is narrow, a page about something that arrived after 6.4, and the note illustrates it with a single version. Nothing in the tree marks which pages fall on which side of that line, which means the decision lands on the person editing rather than on the branch layout.

Work is still landing here. The last push came on 2026-09-28, and GitHub records no releases for the repository, so there is no tagged history to read when you want to know whether a page changed or when.

Chapter files sit beside directories that carry the same name

The top level repeats one pattern: a chapter file paired with a directory of the same name. `cache.rst` sits beside `cache/`, and the same pairing holds for `configuration.rst`, `console.rst`, `controller.rst`, `deployment.rst`, `doctrine.rst`, `frontend.rst`, `http_cache.rst`, `logging.rst`, `messenger.rst` and `bundles.rst`. File and directory divide the work here: the file is the landing page for the chapter, the directory holds the pages underneath it.

The pairing is not universal, and the exceptions carry information. `form/`, `reference/`, `getting_started/`, `introduction/` and `create_framework/` appear as directories with no matching chapter file at the top level, where `index.rst` is the entry point. Other chapters ship no directory at all, among them `routing.rst`, `profiler.rst`, `performance.rst`, `migration.rst`, `lock.rst`, `mime_types.rst`, `object_mapper.rst`, `page_creation.rst` and `rate_limiter.rst`. A one-page chapter and a sprawling one look identical from the top level, so the directory listing is the only size hint a newcomer gets.

One more top-level directory changes how you search. `_includes/` and `_images/` carry a leading character the chapter files never use, and it marks shared assets rather than chapter content, so a phrase that appears inside a chapter page can come from a fragment held outside that chapter's folder. A search limited to `controller/` will miss it, and the tree lists no index of what those fragments contain.

Lint config and an agent file sit beside the chapters

The non-page files in the root are where the editorial rules live, and the README explains almost none of them. `.editorconfig` and `.gitignore` are ordinary. Three deserve attention from anyone opening a pull request: `.doctor-rst.yaml`, named after a checker aimed at reStructuredText, and `.alexrc`, named after the filter that flags wording in documentation. Neither file's contents appear in the tree, and the README does not say what either check rejects, so the rules live in the files rather than in the instructions.

`AGENTS.md` sits next to README.md at the top level. That name follows the cross-tool convention for instructions written for automated coding assistants, which tells you the project expects edits from tooling as well as from people and wants those edits to follow written rules rather than editor defaults.

`LICENSE.md` is a file, and GitHub records the licence of this repository as Other, meaning a custom one it cannot classify. For anyone planning to lift page text into a company handbook, read that file, because no standard identifier will answer the question for you.

Reading the published manual instead of building it

Every step above has an alternative, and it is the one most readers take. The published manual at https://symfony.com/doc/current/index.html needs no clone, no PHP and no WSL, and it carries the same documentation this repository produces. When the goal is learning the framework or looking up a config key, the difference in approach is not quality, it is latency and history: the site hands you the current text, while the repository hands you that text plus its commits and the changes waiting for review.

Screencasts sit beside that path at symfonycasts.com, and the component listing at https://symfony.com/components is the linked way into the framework's own parts. None of them replace the repository when the problem is one specific page: correcting an example that renders wrong, checking whether a sentence still holds on 6.4, or reading the manual on a train all need the local build.

That framing in the README makes the split visible. Building is offered as the debugging and offline path, contributing is offered as a pull request against a branch. A team that only needs to read documentation never runs a command from this repository at all.

Editorial conclusion

Adopt this repository when you write or correct Symfony reference pages and want the change reviewed in the open, and leave the local build alone unless you must debug a rendering problem or read without a connection. It is not a framework checkout and it is not something you install into an application, so a team hunting for component source will find none here. Before the first edit, settle which branch the page belongs to, since a clone hands you 7.4 while the note asks for 6.4, and check that your machine can run the builder, which on Windows means WSL.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. symfony/symfony-docs on GitHub