HYPERFLEET-411: Add HyperFleet directory structure standard documentation #58
Conversation
WalkthroughA new Markdown file, "HyperFleet Directory Structure Standard," was added to define a mandatory repository layout and conventions for HyperFleet projects. It lists required and optional top-level directories (e.g., bin, build, cmd, pkg, internal, configs, openapi, kustomize, helm, docs, scripts, test), describes each directory's purpose, specifies temporary file handling and example placements, and mandates Gitignore patterns and repository-level files (Makefile, Dockerfile, go.mod, README.md). Sequence Diagram(s)(omitted — changes are documentation-only and do not introduce new runtime control flow) Estimated code review effort🎯 1 (Trivial) | ⏱️ ~5 minutes Possibly related PRs
Suggested reviewers
Pre-merge checks✅ Passed checks (3 passed)
📜 Recent review detailsConfiguration used: Organization UI Review profile: CHILL Plan: Pro 📒 Files selected for processing (1)
🧰 Additional context used🪛 markdownlint-cli2 (0.18.1)hyperfleet/docs/directory-structure.md56-56: Fenced code blocks should have a language specified (MD040, fenced-code-language) 🔇 Additional comments (1)
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
📜 Review details
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
hyperfleet/docs/directory-structure.md
🧰 Additional context used
🪛 markdownlint-cli2 (0.18.1)
hyperfleet/docs/directory-structure.md
56-56: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🔇 Additional comments (1)
hyperfleet/docs/directory-structure.md (1)
1-213: Excellent comprehensive documentation on directory structure.The document is well-organized, clearly written, and provides practical guidance for repository standardization. The problem statement, goals, and scope are clearly articulated, and the directory layout is comprehensive with both required and optional sections. The tables effectively summarize directory purposes and
.gitignorerequirements.
| ``` | ||
| repo-root/ | ||
| ├── bin/ # Compiled binaries (gitignored) | ||
| │ └── app-name # Compiled binary (e.g., pull-secret, dns-adapter) | ||
| ├── build/ # Temporary build artifacts (gitignored) | ||
| │ ├── cache/ # Build cache | ||
| │ └── tmp/ # Temporary files | ||
| ├── cmd/ # Main application(s) | ||
| │ └── app-name/ # Application-specific directory (e.g., pull-secret/) | ||
| │ ├── main.go # Main executable | ||
| │ └── jobs/ # Job implementations (if applicable) | ||
| │ └── job.go | ||
| ├── pkg/ # Application libraries and packages | ||
| │ ├── api/ # API client libraries | ||
| │ ├── config/ # Configuration structures | ||
| │ ├── handlers/ # HTTP handlers | ||
| │ ├── services/ # Business logic | ||
| │ ├── models/ # Data models | ||
| │ └── utils/ # Utility functions | ||
| ├── openapi/ # OpenAPI/Swagger specifications (if applicable) | ||
| │ ├── api.yaml # OpenAPI 3.0 specification | ||
| │ └── v1/ # Versioned API specs | ||
| │ └── swagger.json | ||
| ├── k8s/ # Kubernetes manifests | ||
| │ ├── base/ # Base Kustomize configuration | ||
| │ ├── overlays/ # Environment-specific overlays | ||
| │ │ ├── dev/ | ||
| │ │ ├── staging/ | ||
| │ │ └── prod/ | ||
| │ └── crds/ # Custom Resource Definitions (if applicable) | ||
| ├── helm/ # Helm charts (if applicable) | ||
| │ └── chart-name/ # Helm chart directory | ||
| │ ├── Chart.yaml | ||
| │ ├── values.yaml | ||
| │ └── templates/ | ||
| ├── docs/ # Documentation | ||
| │ ├── architecture.md | ||
| │ ├── api.md | ||
| │ └── development.md | ||
| ├── scripts/ # Helper scripts | ||
| │ ├── setup.sh | ||
| │ └── deploy.sh | ||
| ├── test/ # Integration and E2E tests | ||
| │ ├── integration/ | ||
| │ └── e2e/ | ||
| ├── .github/ # GitHub configuration | ||
| │ └── workflows/ # GitHub Actions | ||
| ├── Makefile # Standard Makefile (see makefile-conventions.md) | ||
| ├── Dockerfile # Container definition | ||
| ├── .gitignore # Git ignore rules | ||
| ├── go.mod # Go module definition (for Go projects) | ||
| ├── go.sum # Go module checksums | ||
| └── README.md # Project documentation | ||
| ``` |
There was a problem hiding this comment.
Add language specification to the directory tree code block.
The fenced code block is missing a language identifier. While the tree structure itself is clear, specifying the language improves rendering in tools and documentation systems.
🔎 Proposed fix
-```
+```text
repo-root/
├── bin/ # Compiled binaries (gitignored)🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
56-56: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
In hyperfleet/docs/directory-structure.md around lines 56 to 109, the fenced
code block showing the repo tree lacks a language identifier; update the opening
fence from ``` to ```text (or another appropriate identifier like ```bash) so
the block becomes ```text repo-root/... and leave the closing ``` unchanged to
improve rendering.
| | `bin/` | Compiled binaries | Yes | Must be in `.gitignore` | | ||
| | `cmd/` | Main application entry points | Yes | One subdirectory per executable | | ||
| | `pkg/` | Application libraries and packages | Yes | All reusable code and business logic | | ||
| | `Makefile` | Build automation | Yes | See [makefile-conventions.md](makefile-conventions.md) | |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Check if makefile-conventions.md exists in the docs directory
fd "makefile-conventions.md" hyperfleet/docs/
# If found, verify it's accessible and has content
if [ -f "hyperfleet/docs/makefile-conventions.md" ]; then
echo "File exists. First 10 lines:"
head -10 "hyperfleet/docs/makefile-conventions.md"
else
echo "File not found in expected location"
fi
# Also check all lines in directory-structure.md that reference makefile-conventions
echo ""
echo "References in directory-structure.md:"
rg "makefile-conventions" hyperfleet/docs/directory-structure.mdRepository: openshift-hyperfleet/architecture
Length of output: 404
Create the missing makefile-conventions.md document or remove the broken references.
The file makefile-conventions.md is referenced in directory-structure.md at lines 122 and 207 but does not exist in the hyperfleet/docs/ directory. Either create this document or update the references to point to an existing file.
🤖 Prompt for AI Agents
In hyperfleet/docs/directory-structure.md around lines 122 and 207, the document
references makefile-conventions.md which does not exist; either add a new file
hyperfleet/docs/makefile-conventions.md containing the Makefile conventions
(purpose, targets, variables, examples, and repository conventions) and commit
it, or update both references in directory-structure.md to point to an existing,
correct document or remove the link text entirely so there are no broken
references.
|
|
||
| ``` | ||
| repo-root/ | ||
| ├── bin/ # Compiled binaries (gitignored) |
There was a problem hiding this comment.
I assume bin and build are both added in gitignore. From remote repo, we won't see this too directories.
There was a problem hiding this comment.
Absolutely! According to directory-structure.md, both the bin/ and build/ directories are designed to be excluded via .gitignore.
| │ ├── main.go # Main executable | ||
| │ └── jobs/ # Job implementations (if applicable) | ||
| │ └── job.go | ||
| ├── pkg/ # Application libraries and packages |
There was a problem hiding this comment.
Right now, both sentinel and adapter framework have pkg and internal packages. pkg mainly focus on logger and errors and other packages can be shared. internal used to put the packages used internally in current service. It's great to have the rule unified, I am think which one is better. internal+pkg vs pkg only
There was a problem hiding this comment.
Initially, I designed the internal/ directory based on a pattern available in the Go standard project layout. However, after reviewing other HCM projects, I noticed that teams usually consolidate pkg/ and internal/ into a single pkg/ folder. Anyway, I’m fine with either approach. We can also keep both: pkg/ for shared libraries and internal/ for private application code (handlers, services, models, etc.). Does that make sense?
| │ └── job.go | ||
| ├── pkg/ # Application libraries and packages | ||
| │ ├── api/ # API client libraries | ||
| │ ├── config/ # Configuration structures |
There was a problem hiding this comment.
how about the configuration files?
There was a problem hiding this comment.
Added in the latest commit.
| |-----------|---------|-------------|-------| | ||
| | `build/` | Temporary build artifacts | If build generates temporary files | Must be in `.gitignore` | | ||
| | `openapi/` | OpenAPI/Swagger specifications | If repo defines APIs via OpenAPI specs | YAML/JSON files, committed to Git | | ||
| | `k8s/` | Kubernetes manifests | If repo deploys to Kubernetes | Use Kustomize structure | |
There was a problem hiding this comment.
hmm...as we are using helm for helm charts, maybe this one can use kustomize directly rather than k8s that will cause confusion
There was a problem hiding this comment.
Got it! I tried to address your feedback in the latest commit.
2 participants
This PR adds comprehensive documentation for the standard directory structure, related to HYPERFLEET-411.
Summary by CodeRabbit
✏️ Tip: You can customize this high-level summary in your review settings.