Skip to content

[Bug] docs/ddg.md points at fast/stages-aw/2-networking-a-fedramp-high, which v3.0.0 renamed — the deployment guide's networking step cannot be followed #196

Description

@JohnHales

Bug Description

v3.0.0 renamed fast/stages-aw/2-networking-a-fedramp-high to fast/stages-aw/2-networking-a-fedramp, but the documentation was only partly swept. docs/ddg.md still instructs operators to change directory into the old path, twice — at line 429, inside the section headed "FedRAMP High / Moderate - Stage 2.1 Networking", and again at line 639 under "Apply FAST Stage: 02-networking". Following the deployment guide on v3.0.0 or main therefore fails at the networking stage. docs/tdd.md:617 also still lists the old directory in its repository-structure tree.

The sweep was partial rather than missed entirely: docs/tdd.md:946 was updated and now reads "FedRAMP High / Moderate Pattern (2-networking-a-fedramp)", so the design section is current while the deployment steps and the tree listing are not. The DDG is the document an operator follows end to end, so a wrong path there is a hard stop rather than a cosmetic inconsistency.

Environment and Deployment Context

  • Stellar Engine Version/Commit: main (also reproduces at the v3.0.0 tag, f64ce6cd)
  • Deployment Type:
    • US Region Restricted (e.g., Access Policy constraint)
    • FedRAMP Medium
    • FedRAMP High
    • FedRAMP Moderate
    • DoD IL4
    • DoD IL5
    • Stand-alone / Custom
  • FAST Stage (if applicable):
    • Stage 0 (Bootstrap)
    • Stage 1 (Resource Management)
    • Stage 2 (Network Creation)
    • Stage 3 (Security and Audit)
  • Affected Component: docs/ddg.md, docs/tdd.md, fast/stages-aw/2-networking-a-fedramp
  • Terraform Version: not reached — the guide fails before terraform init (our environment runs 1.15.7)
  • GCP Provider Version: not reached (our environment pins hashicorp/google 6.50.0)

Steps to Reproduce

  1. Clone the repository at main, or check out the v3.0.0 tag.
  2. Open docs/ddg.md and go to the section "FedRAMP High / Moderate - Stage 2.1 Networking".
  3. Follow the step at line 429: "Change directory into fast/stages-aw/2-networking-a-fedramp-high".
  4. The directory does not exist. The same instruction appears again at line 639.

Expected Behavior

The deployment guide names a directory that exists in the tree it ships with, so an operator can follow the FedRAMP High / Moderate networking stage from start to finish without having to discover the correct path themselves.

Actual Behavior

The path does not exist at v3.0.0 or main. Verified against the repository tree: fast/stages-aw/ contains 2-networking-a-fedramp-high at 8f5b67a6 (v2.13.0) and at 3728fc98, and 2-networking-a-fedramp at f64ce6cd (v3.0.0) and at main. The rename landed in #162 (7033b8cc, merged 2026-08-10), with README updates in #173.

Reference Path named Correct at main?
docs/ddg.md:429 fast/stages-aw/2-networking-a-fedramp-high No
docs/ddg.md:639 fast/stages-aw/2-networking-a-fedramp-high No
docs/tdd.md:617 2-networking-a-fedramp-high No
docs/tdd.md:946 2-networking-a-fedramp Yes

Relevant Logs and Errors

$ git checkout v3.0.0
$ cd fast/stages-aw/2-networking-a-fedramp-high
bash: cd: fast/stages-aw/2-networking-a-fedramp-high: No such file or directory

$ ls fast/stages-aw/
0-bootstrap  1-resman  2-networking-a-fedramp  2-networking-b-il5-ngfw  3-security

Additional Context

Migration notes for the rename. releases.md states that major releases "will include detailed migration notes, state refactoring scripts, or step-by-step instructions for upgrading existing environments without unexpected downtime or state drift." Renaming a Terraform root module changes both the working directory and, for anyone whose backend prefix follows the directory, the state location — exactly the case that policy describes. We could not find notes for it: the repository has 15 tags and no published GitHub Releases, and no upgrade or migration document in the tree. Even a short note saying "rename only, no state action required" would close this out for operators upgrading an existing landing zone.

This is the same change discussed in #195, which asks what else about it went unrecorded — that issue is about the design decision behind the rename and is not resolved by fixing these paths.

Metadata

Metadata

Assignees

No one assigned

    Labels

    bugSomething isn't working

    Type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions