Feature/validate

.github/workflows/build.yml

@@ -1,26 +1,32 @@
 name: build
+
 on:
   push:
-    branches: [ main ]
+    branches: [ main, feature/* ]
   pull_request:
     branches: [ main ]
   merge_group:
 
 jobs:
   pre-commit:
     runs-on: ubuntu-latest
+
     steps:
-      - uses: actions/checkout@v4
+      - name: Checkout repository
+        uses: actions/checkout@v4
 
-      - uses: meshcloud/setup-collie@main
+      - name: Set up meshcloud collie CLI
+        uses: meshcloud/setup-collie@main
 
-      - uses: nixbuild/nix-quick-install-action@v26
+      - name: Install Nix
+        uses: nixbuild/nix-quick-install-action@v26
         with:
           nix_on_tmpfs: true
 
-      - uses: rrbutani/use-nix-shell-action@v1
+      - name: Enter nix dev shell
+        uses: rrbutani/use-nix-shell-action@v1
         with:
-          devShell: .#github_actions # use a special github actions shell
+          devShell: .#github_actions
 
-      - name: ensure all pre-commit hooks pass
+      - name: Run pre-commit checks
         run: pre-commit run --all-files --show-diff-on-failure

.gitignore

@@ -1,3 +1,4 @@
+# angular
 /.idea/
 
 .DS_Store
@@ -13,4 +14,51 @@ yarn-error.log*
 .vscode/
 .idea/
 *.iml
-.angular/
+.angular/
+
+# Local .terraform directories
+**/.terraform/*
+
+# .tfstate files
+*.tfstate
+*.tfstate.*
+
+# Crash log files
+crash.log
+
+# Exclude all .tfvars files, which are likely to contain sentitive data, such as
+# password, private keys, and other secrets. These should not be part of version
+# control as they are data points which are potentially sensitive and subject
+# to change depending on the environment.
+#
+*.tfvars
+
+# Ignore override files as they are usually used to override resources locally and so
+# are not checked in
+override.tf
+override.tf.json
+*_override.tf
+*_override.tf.json
+
+# Include override files you do wish to add to version control using negated pattern
+#
+# !example_override.tf
+
+# Include tfplan files to ignore the plan output of command: terraform plan -out=tfplan
+# example: *tfplan*
+
+# Ignore CLI configuration files
+.terraformrc
+terraform.rc
+
+# Terraform Lock-Dateien
+.terraform.lock.hcl
+**/.terraform.lock.hcl
+
+# Terragrunt Cache
+.terragrunt-cache/
+**/.terragrunt-cache/
+
+# Testverzeichnisse
+/testing/
+**/testing/

.pre-commit-config.yaml

@@ -1,4 +1,19 @@
 repos:
+  - repo: local
+    hooks:
+      - id: check-terraform-structure
+        name: Check Terraform module structure
+        entry: bash ci/check_tf_structure.sh modules/**/{backplane,buildingblock}
+        language: system
+        pass_filenames: false
+  - repo: local
+    hooks:
+      - id: validate-buildingblock
+        name: Validate README and PNG in buildingblocks
+        entry: bash ci/validate_modules.sh
+        language: system
+        pass_filenames: false
+
   - repo: https://github.com/antonbabenko/pre-commit-terraform
     rev: v1.81.0
     hooks:
@@ -7,8 +22,12 @@ repos:
             - --args=--config=.terraform-docs.yml
       - id: terraform_fmt
       - id: terragrunt_fmt
+      - id: terraform_validate
+        exclude:
+          #some of the validation have to be excluded because the provider.tf cant be validated
+          ^modules/(github/repository|aks/(github-connector|postgresql))/buildingblock/
+
   - repo: https://github.com/pre-commit/pre-commit-hooks
     rev: v4.4.0  # Use the ref you want to point at
     hooks:
       - id: trailing-whitespace
-        exclude: "^compliance/"

README.md

@@ -50,3 +50,106 @@ Refer to each module's README.md for specific usage instructions such as needed
 
 The meshStack Hub is a 🌤️ [cloudfoundation.org community](https://cloudfoundation.org/?ref=github-collie-cli) project.
 Reach out to us on the [cloudfoundation.org slack](http://cloudfoundationorg.slack.com).
+
+## 🛠️ How to Contribute
+
+Thank you for your interest in contributing Terraform modules or building blocks to **meshstack-hub**! To ensure high quality and consistency, please follow the steps below:
+
+---
+
+### 1. Fork & Clone
+
+```bash
+git clone [email protected]:<your-username>/meshstack-hub.git
+cd meshstack-hub
+git checkout -b feature/your-module
+```
+
+---
+
+### 2. Enter Nix Development Shell
+
+The repository provides a `flake.nix` that includes pre-commit hooks, formatting, validation, and docs generation:
+
+```bash
+nix develop
+```
+
+This prepares the environment with `terraform`, `terraform-docs`, `pre-commit`, and any other needed tools automatically.
+
+---
+
+### 3. Write and Organize Your Terraform Module
+
+- Add your module under the correct provider folder (e.g. `aws/`, `azure/`, `gcp/`).
+- Include:
+  - `main.tf`, `variables.tf`, `outputs.tf`, `versions.tf`, `providers.tf`, `APP_TEAM_README.md`
+  - A `README.md` describing the module’s purpose and usage.
+
+---
+
+### 4. Run Pre‑commit Hooks
+
+Hooks are already available in your shell:
+
+```bash
+pre-commit run --all-files
+```
+
+They include checks like `terraform fmt`, `terraform validate` and automated docs via `terraform-docs`.
+
+Commiting will auto-run them:
+
+```bash
+git add .
+git commit -m "feat: add new vpc module"
+```
+
+---
+
+This is typically triggered via pre-commit hooks during commits.
+
+---
+
+### 7. Add or Update Tests
+
+- Run them inside `nix develop`, for example:
+
+Ensure all tests pass and code/formats stay clean.
+
+---
+
+### 8. Push & Open a Pull Request
+
+```bash
+git push origin feature/your-module
+```
+
+In your PR description include:
+- Module purpose, inputs/outputs
+- Provider details
+- Any breaking changes or migration notes
+- Confirmation that all tests and checks passed
+
+---
+
+### 9. Review & Merge
+
+CI will rerun all hooks/tests. A maintainer will review and merge or request adjustments.
+
+---
+
+## ✅ Summary Checklist
+
+1. [ ] Module in the correct provider folder
+2. [ ] `main.tf`, `variables.tf`, `outputs.tf`, `README.md`
+3. [ ] `nix develop` used to enter environment ✅
+4. [ ] `pre-commit run --all-files` passed ✅
+5. [ ] `terraform init`, `validate`, `fmt` passed ✅
+6. [ ] `terraform-docs markdown .` docs generated ✅
+7. [ ] Tests added/updated and passing ✅
+8. [ ] PR includes description & proof that all checks passed ✅
+
+---
+
+Thanks again for helping to improve **meshstack-hub**! 🚀

ci/check_tf_structure.sh

@@ -0,0 +1,42 @@
+#!/bin/bash
+set -e
+
+warnings=()
+
+# Required Terraform files
+common_tf_files=("main.tf" "variables.tf" "outputs.tf" "provider.tf" "versions.tf")
+readme_file="APP_TEAM_README.md"
+
+# Find relevant module directories
+mapfile -t paths_to_check < <(find modules/ -type d \( -path "*/buildingblock" -o -path "*/backplane" \))
+
+if [ "${#paths_to_check[@]}" -eq 0 ]; then
+  echo "❌ No Terraform module folders found."
+  exit 1
+fi
+
+# Check each directory silently unless a file is missing
+for path in "${paths_to_check[@]}"; do
+  for tf_file in "${common_tf_files[@]}"; do
+    if [[ ! -f "$path/$tf_file" ]]; then
+      warnings+=("⚠️  '$tf_file' is missing in $path")
+    fi
+  done
+
+  if [[ "$(basename "$path")" == "buildingblock" ]]; then
+    if [[ ! -f "$path/$readme_file" ]]; then
+      warnings+=("⚠️  '$readme_file' is missing in $path")
+    fi
+  fi
+done
+
+# Output only if something's wrong
+if [ "${#warnings[@]}" -gt 0 ]; then
+  echo "❌ Issues detected:"
+  for warn in "${warnings[@]}"; do
+    echo "$warn"
+  done
+  exit 1
+else
+  exit 0
+fi