google / google/stellar-engine
[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
- Dominant language
- HCL
- Stars
- 49
- Forks
- 20
- Avg merge
- 3d 14h
- Merged PRs (30d)
- 28
Description
## 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
* [x] FedRAMP High
* [x] FedRAMP Moderate
* [ ] DoD IL4
* [ ] DoD IL5
* [ ] Stand-alone / Custom
* **FAST Stage (if applicable):**
* [ ] Stage 0 (Bootstrap)
* [ ] Stage 1 (Resource Management)
* [x] 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](https://github.com/google/stellar-engine/pull/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](https://github.com/google/stellar-engine/issues/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.
Contributor guide
Research direction
Read docs/ddg.md at lines 429 and 639 and docs/tdd.md at line 617, using docs/tdd.md:946 and the fast/stages-aw tree as the current naming references. Verify the old path no longer appears, then follow the affected deployment-guide steps far enough to confirm they point to an existing directory; done means the guide and repository tree consistently use 2-networking-a-fedramp.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- terraform
- Domain
- documentation
- Issue type
- Bug
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Active
- Clarity
- Clearly specified
- Newbie friendliness
- 88/100