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

Open Beginner friendly
#196 0 comments 0 reactions 0 assignees View on GitHub
bug Level of Effort - Low Priority - Medium
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.