Merge pull request #913 from sonoflawal/fix/issues-908-909-910-911-cleanup-conventions-deadcode-config

fix: resolve issues #908 #909 #910 #911 — dead code audit, config def…

Author: OtowoSamuel

CONTRIBUTING.md

@@ -182,7 +182,46 @@ make ci-local
 - Document behavior changes in code comments and docs.
 - Keep PRs small and easy to review.
 
-## 9. Need Help?
+### Rust code conventions
+
+- Module names use `snake_case`.
+- Public types and functions require doc comments (`///`).
+- Do not add `#[allow(dead_code)]` without a comment explaining why the code must stay.
+- Unused imports must be removed before merging.
+- Feature-gated code that is no longer used should be deleted, not suppressed.
+
+### Documentation conventions
+
+- Documentation files use `kebab-case.md` (e.g., `disk-scaling.md`).
+- Files that belong to a topic area go in the matching `docs/<topic>/` subdirectory.
+- Root-level docs (`README.md`, `DEVELOPMENT.md`, `CONTRIBUTING.md`) are entry points only — detailed content belongs in `docs/`.
+- New doc files must be linked from `docs/README.md` under the appropriate section.
+
+### Script conventions
+
+- Scripts use `kebab-case.sh` (e.g., `setup-mac.sh`).
+- Every script must pass `shellcheck -S error`.
+- Historical or one-off scripts should be moved to `scripts/archive/` rather than left in the root of `scripts/`.
+
+### Manifest and config conventions
+
+- CRD YAML files follow the `stellar{feature}-crd.yaml` naming pattern under `config/crd/`.
+- Example manifests in `examples/` use descriptive, feature-based names — not issue numbers.
+- Generated manifests (CRDs, API reference, bundle) must be regenerated from their source before merging. See the [Regenerating Manifests](DEVELOPMENT.md#regenerating-manifests) table in DEVELOPMENT.md.
+
+## 9. Repo Health Checklist
+
+Run through this before marking a PR ready for review:
+
+- [ ] `make ci-local` passes (format + lint + audit + test + build)
+- [ ] No new `#[allow(dead_code)]` without an explanatory comment
+- [ ] No unused imports in modified files
+- [ ] Generated manifests are up to date with their source
+- [ ] Shell scripts pass `shellcheck -S error`
+- [ ] New doc files are linked from `docs/README.md`
+- [ ] Commit messages follow Conventional Commits and include a `Signed-off-by` line
+
+## 10. Need Help?
 
 If you're stuck, open a Draft PR or create an issue to ask for guidance.
 

CONVENTIONS.md

@@ -0,0 +1,139 @@
+# Repository Conventions
+
+This document defines the naming and structural conventions for the Stellar-K8s repository.
+Following these conventions keeps the directory tree easy to skim and reduces surprises for
+contributors navigating the codebase for the first time.
+
+---
+
+## Directory Layout
+
+```
+Stellar-K8s/
+├── assets/              Logo and static images
+├── benchmarks/          k6 performance tests and baseline results
+├── bundle/              OLM bundle (generated — do not hand-edit)
+├── charts/              Helm charts
+│   └── stellar-operator/
+├── config/              Kubernetes manifests and CRDs (see config/README.md)
+│   ├── crd/             Generated CRD YAML files
+│   ├── samples/         Example resources for testing
+│   ├── manifests/       OLM CSV bases and Gatekeeper policies
+│   └── dev/             Local dev kubeconfigs (not for production)
+├── docs/                All project documentation (see docs/README.md)
+├── examples/            Ready-to-use StellarNode manifests
+├── monitoring/          Grafana dashboards and Prometheus alert rules
+├── policy/              CEL and OPA policies
+├── schemas/             JSON schemas
+├── scripts/             Operational scripts
+│   ├── dev-utils/       Development helper utilities
+│   ├── lib/             Shared script library functions
+│   └── archive/         Historical one-off scripts (not part of normal workflow)
+├── security/            Security policies and SBOM
+├── src/                 Rust source code
+├── tests/               Integration and E2E tests
+└── tools/               CLI and utility tools
+```
+
+Each top-level directory has a single, obvious purpose. If a new directory is needed, add it
+here and keep its name lowercase with hyphens (`kebab-case`).
+
+---
+
+## Naming Rules
+
+### Rust source files and modules
+
+| Element | Convention | Example |
+|---|---|---|
+| File names | `snake_case.rs` | `disk_scaler.rs` |
+| Module directories | `snake_case/` | `rest_api/` |
+| Public types and traits | `UpperCamelCase` | `StellarNode` |
+| Public functions | `snake_case` | `reconcile_node` |
+| Constants | `SCREAMING_SNAKE_CASE` | `STELLAR_NODE_FINALIZER` |
+| Feature flags (`#[cfg]`) | `kebab-case` | `rest-api`, `metrics` |
+
+### Documentation files
+
+| Element | Convention | Example |
+|---|---|---|
+| File names | `kebab-case.md` | `disk-scaling.md` |
+| Directory names | `kebab-case/` | `deployment-guides/` |
+| Root-level docs | ALL-CAPS.md for repo meta | `README.md`, `CONTRIBUTING.md` |
+
+Documentation files that belong to a topic area go in the matching `docs/<topic>/` subdirectory.
+Root-level files (`README.md`, `DEVELOPMENT.md`, `CONTRIBUTING.md`, `CONVENTIONS.md`) are
+entry points only — detailed content belongs in `docs/`.
+
+### Shell scripts
+
+| Element | Convention | Example |
+|---|---|---|
+| File names | `kebab-case.sh` | `setup-mac.sh` |
+| Operational scripts | live in `scripts/` | `scripts/validate.sh` |
+| Historical / one-off | move to `scripts/archive/` | `scripts/archive/create_batch_2_issues.sh` |
+
+Every script must pass `shellcheck -S error` before merging.
+
+### Kubernetes manifests
+
+| Element | Convention | Example |
+|---|---|---|
+| CRD files | `stellar{feature}-crd.yaml` | `stellarnode-crd.yaml` |
+| Sample files | descriptive, lowercase, hyphens | `test-stellarnode.yaml` |
+| Example files | feature-based, no issue numbers | `validator-mainnet.yaml` |
+| Helm chart values | `values.yaml` (defaults), `values-ha.yaml` (variants) | — |
+
+**CRD naming**: All CRD YAML files under `config/crd/` follow the `stellar{feature}-crd.yaml`
+pattern. The resource kind in the file itself uses `UpperCamelCase` (e.g. `StellarNode`).
+
+**Example manifests**: Files in `examples/` use descriptive, feature-based names. Issue numbers
+must not appear in filenames — use the feature name instead
+(e.g. `advanced-features-compliance-upgrade-scaling.yaml`, not `advanced-features-500-503.yaml`).
+
+---
+
+## File Placement Rules
+
+1. **Source files**: Go in the most specific module directory under `src/`. Do not place new
+   `.rs` files directly in `src/` unless they are top-level entry points (`main.rs`, `lib.rs`,
+   `error.rs`, `cli.rs`).
+
+2. **Documentation files**: Go in the matching `docs/<topic>/` subdirectory. New files must be
+   linked from `docs/README.md` under the appropriate section.
+
+3. **Config files**: Go under `config/` with a clear subdirectory. Use `config/crd/` for CRDs,
+   `config/samples/` for test resources, and `config/manifests/` for OLM bases.
+
+4. **Scripts**: Operational scripts go in `scripts/`. One-off or historical scripts go in
+   `scripts/archive/`. Scripts must not live at the repository root.
+
+5. **Generated files**: Never hand-edit generated files. Always regenerate from source.
+   See the [Regenerating Manifests](DEVELOPMENT.md#regenerating-manifests) table.
+
+---
+
+## Generated vs Hand-Written Files
+
+| File or directory | Hand-written? | Source of truth |
+|---|---|---|
+| `config/crd/*.yaml` | No | `src/crd/` Rust types |
+| `bundle/manifests/*.yaml` | No | `config/manifests/bases/` + operator-sdk |
+| `docs/api-reference.md` | No | `src/crd/` + `make generate-api-docs` |
+| Shell completions | No | `src/cli.rs` + `make completions` |
+| `charts/stellar-operator/values.yaml` | Yes | — |
+| `config/operator-config.yaml` | Yes | — |
+| `docs/**/*.md` (other than api-reference) | Yes | — |
+
+---
+
+## Enforcement
+
+These conventions are enforced by:
+
+- **Pre-commit hooks** (`shellcheck`, `cargo fmt`, `yamllint`) — run `make pre-commit-install`
+- **CI lint step** (`cargo clippy`, `make fmt-check`) — runs on every PR
+- **PR checklist** in [CONTRIBUTING.md](CONTRIBUTING.md#9-repo-health-checklist)
+
+If you find a file that violates these conventions and is not covered by the checklist, open
+a PR to fix it or add it to the checklist.

DEVELOPMENT.md

@@ -713,4 +713,62 @@ E2E_OPERATOR_IMAGE=stellar-operator:dev  # Custom operator image for E2E
 
 ---
 
+## Repo Health Checklist
+
+Use this checklist before merging any PR that touches code, scripts, or documentation. It captures the minimum bar to keep the repository clean and navigable.
+
+### Code Quality
+
+- [ ] `make fmt-check` passes (no unformatted Rust code)
+- [ ] `make lint` passes (no clippy warnings at the deny level)
+- [ ] `make audit` passes or all advisories are reviewed and acknowledged
+- [ ] `make test` passes locally
+- [ ] No new `#[allow(dead_code)]` attributes added without a comment explaining why
+- [ ] No unused `use` imports left in modified files
+- [ ] New public functions and types have doc comments
+
+### Documentation
+
+- [ ] Any user-facing behavior change is reflected in `docs/` or the relevant doc file
+- [ ] New `make` targets are listed under **Useful Make Targets** in this file
+- [ ] New environment variables are listed under **Environment Variables** in the Quick Reference
+- [ ] CRD field changes trigger `make generate-api-docs` to regenerate `docs/api-reference.md`
+
+### Scripts and Manifests
+
+- [ ] Shell scripts pass `shellcheck -S error`
+- [ ] New config files go under `config/` with a clear subdirectory (see `config/README.md`)
+- [ ] Helm values changes are reflected in `charts/stellar-operator/values.yaml` comments
+- [ ] Generated manifests are regenerated from their source (see [Regenerating Manifests](#regenerating-manifests))
+
+### Naming
+
+- [ ] Rust modules use `snake_case`
+- [ ] Documentation files use `kebab-case.md`
+- [ ] CRD YAML files follow the `stellar{feature}-crd.yaml` pattern
+- [ ] Example manifests use descriptive names, not issue-number-based names
+
+### Final
+
+- [ ] `make ci-local` passes end-to-end (format + lint + audit + test + build)
+- [ ] Branch is up to date with `main`
+- [ ] Commit messages follow Conventional Commits
+
+---
+
+## Regenerating Manifests
+
+Several files in this repo are generated from a source of truth. Always regenerate them after changing the source.
+
+| Generated file | Source of truth | Regeneration command |
+|---|---|---|
+| `docs/api-reference.md` | CRD types in `src/crd/` | `make generate-api-docs` |
+| `config/crd/*.yaml` | CRD structs in `src/crd/` | `make crd-gen` |
+| `bundle/manifests/*.yaml` | `config/manifests/bases/` + operator metadata | `make bundle` (requires operator-sdk) |
+| Shell completions | CLI definitions in `src/cli.rs` | `make completions` |
+
+After running any of the above, commit the updated generated file alongside the source change in the same PR.
+
+---
+
 Happy coding! If you encounter issues not covered here, please open an issue or ask in the community channels.

README.md

@@ -321,6 +321,20 @@ featureFlags:
 
 We welcome contributions! This project uses pre-commit hooks to ensure code quality. Please see our [Contributing Guide](CONTRIBUTING.md) for details on our development process, coding standards, and how to submit pull requests.
 
+### Repo Health Checklist
+
+Before opening a PR, run through this quick checklist to keep the repo clean:
+
+- `make ci-local` — runs format check, lint, security audit, tests, and build in one step
+- `make fmt` — auto-formats all Rust code
+- `make lint` — runs clippy at the deny level
+- `make audit` — scans dependencies for known vulnerabilities
+- `shellcheck -S error scripts/*.sh` — validates shell scripts
+- `make generate-api-docs` — regenerates `docs/api-reference.md` after CRD changes
+- `make crd-gen` — regenerates `config/crd/` manifests after CRD type changes
+
+For the full checklist and expected conventions for docs, scripts, and code, see [DEVELOPMENT.md](DEVELOPMENT.md#repo-health-checklist), [CONTRIBUTING.md](CONTRIBUTING.md#9-repo-health-checklist), and [CONVENTIONS.md](CONVENTIONS.md).
+
 ### Quick Start for Contributors
 
 ```bash