Skip to content
This repository was archived by the owner on May 16, 2026. It is now read-only.

Update module requirements and coding standard #276

Merged
akuzminsky merged 1 commit into from
May 6, 2026
Merged

Update module requirements and coding standard #276

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 1 addition & 4 deletions modules/plain-repo/files/CODING_STANDARD.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -398,11 +398,10 @@ This document defines coding standards for InfraHouse projects.
- `docs/index.md` - Overview, features, quick start
- `docs/getting-started.md` - Prerequisites, first deployment
- `docs/configuration.md` - All variables explained with examples
* **Recommended pages:**
- `docs/architecture.md` - How it works, diagrams
- `docs/examples.md` - Common use cases with explanations
- `docs/troubleshooting.md` - Common issues and solutions
- `docs/changelog.md` - Or link to CHANGELOG.md
- `docs/changelog.md` - Symlink to CHANGELOG.md (`ln -fs ../CHANGELOG.md docs/changelog.md`)
* **Optional pages:**
- `docs/comparison.md` - vs alternatives
- `docs/security.md` - Security considerations
Expand All @@ -423,8 +422,6 @@ This document defines coding standards for InfraHouse projects.
- `CONTRIBUTING.md` - Contribution guidelines
- `SECURITY.md` - Security policy, how to report vulnerabilities
- `CODEOWNERS` - Auto-assign reviewers
- `.github/ISSUE_TEMPLATE/` - Bug report, feature request templates
- `.github/PULL_REQUEST_TEMPLATE.md` - PR template

### Release Automation
* **Automated via `.github/workflows/release.yml`** (managed by github-control)
Expand Down
233 changes: 150 additions & 83 deletions modules/plain-repo/files/TERRAFORM_MODULE_REQUIREMENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,14 +15,14 @@ Provide comprehensive, professional documentation and tooling for all InfraHouse
- Module name and tagline
- Comprehensive badge row

**Badges to include:**
- **Terraform Registry**: `[![Registry](https://img.shields.io/badge/terraform-registry-623CE4?logo=terraform)](registry url)`
- **Latest Release**: `[![GitHub release](https://img.shields.io/github/v/release/infrahouse/repo-name)](release url)`
- **License**: `[![License](https://img.shields.io/github/license/infrahouse/repo-name)](LICENSE)`
**Badges (in this order):**
- **Contact**: `[![Need Help?](https://img.shields.io/badge/Need%20Help%3F-Contact%20Us-0066CC)](https://infrahouse.com/contact)`
- **Documentation**: `[![Docs](https://img.shields.io/badge/docs-github.io-blue)](https://infrahouse.github.io/repo-name/)`
- **Security**: `[![Security](https://github.com/infrahouse/repo-name/actions/workflows/vuln-scanner-pr.yml/badge.svg)](workflow url)`
- **AWS Service Badge(s)**: Link to relevant AWS service(s) the module uses (e.g., Lambda, ECS, RDS). Use shields.io badges with AWS service logos.
- **Contact/Services**: `[![Need Help?](https://img.shields.io/badge/Need%20Help%3F-Contact%20Us-0066CC)](https://infrahouse.com/contact)` - Call to action for professional services
- **Terraform Registry**: `[![Registry](https://img.shields.io/badge/Terraform-Registry-purple?logo=terraform)](https://registry.terraform.io/modules/infrahouse/module-name/aws/latest)`
- **Latest Release**: `[![Release](https://img.shields.io/github/release/infrahouse/repo-name.svg)](https://github.com/infrahouse/repo-name/releases/latest)`
- **AWS Service Badge(s)**: `[![AWS EC2](https://img.shields.io/badge/AWS-EC2-orange?logo=amazonec2)](https://aws.amazon.com/ec2/)` (link to relevant AWS service(s))
- **Security**: `[![Security](https://img.shields.io/github/actions/workflow/status/infrahouse/repo-name/vuln-scanner-pr.yml?label=Security)](https://github.com/infrahouse/repo-name/actions/workflows/vuln-scanner-pr.yml)`
- **License**: `[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)`

**Content Sections:**
1. Brief description (what it does, why it exists)
Expand All @@ -45,14 +45,35 @@ Provide comprehensive, professional documentation and tooling for all InfraHouse
- `configuration.md` - All variables explained
- `examples.md` - Common use cases
- `troubleshooting.md` - Common issues
- `changelog.md` - Or link to CHANGELOG.md
- `changelog.md` - Symlink to CHANGELOG.md (`ln -fs ../CHANGELOG.md docs/changelog.md`)

**Optional but Recommended:**
- `comparison.md` - vs alternatives
- `security.md` - Security considerations
- `monitoring.md` - Observability setup
- `upgrading.md` - Migration guides

**Documentation Dependencies (`requirements.txt`):**
```
diagrams ~= 0.25
mkdocs-material ~= 9.7
mkdocs-minify-plugin ~= 0.8
mkdocs-glightbox ~= 0.4
```

**`mkdocs.yml` Configuration:**
- `site_name` must follow the pattern `InfraHouse <module name>`, where the `terraform-aws-` prefix
is omitted. For example, for `terraform-aws-actions-runner` the site name is
`InfraHouse actions-runner`.
- The `glightbox` plugin must be enabled:
```yaml
plugins:
- search
- glightbox
- minify:
minify_html: true
```

### 3. Repository Files

**Must Have:**
Expand All @@ -69,21 +90,37 @@ Provide comprehensive, professional documentation and tooling for all InfraHouse
- `CONTRIBUTING.md` (contribution guidelines)
- `SECURITY.md` (security policy, how to report vulnerabilities)
- `CODEOWNERS` (auto-assign reviewers)
- `.github/ISSUE_TEMPLATE/` (bug report, feature request)
- `.github/PULL_REQUEST_TEMPLATE.md`

### 4. Testing & Quality

- Working examples in `examples/` that can be tested
- `tests/` directory with pytest-based integration tests
- Uses pytest-infrahouse fixtures
- Uses infrahouse-core for validation
- Tests against multiple AWS provider versions
- Target AWS provider version: `~> 6.0` (AWS 5.x is being deprecated)
- Tests must use `aws_provider_version` parametrize to specify the provider version:
```python
@pytest.mark.parametrize(
"aws_provider_version", ["~> 6.0"], ids=["aws-6"]
)
def test_module(
...
aws_provider_version,
):
```
- Makefile targets: `test-keep`/`test-clean` (for development), `test` (for CI)
- Pre-commit hooks (terraform fmt, terraform-docs, tflint)
- `make bootstrap` must install pre-commit hooks (via `install-hooks` dependency)
- Automated CI/CD with terraform validate and plan
- Security scanning (OSV, checkov, tfsec)

**Security Dependencies (`requirements.txt`):**
```
checkov ~= 3.2
```

The repository must contain a `.checkov.yml` configuration file.

### 5. Release Automation

**GitHub Release Workflow** (`.github/workflows/release.yml`):
Expand Down Expand Up @@ -114,83 +151,113 @@ jobs:
```

**Release Process** (via Makefile targets):
```makefile
release-patch:
git-cliff --tag $(shell bumpversion --dry-run --list patch | grep new_version | cut -d= -f2) -o CHANGELOG.md
bumpversion patch
git push && git push --tags
# GitHub Actions workflow automatically creates the release
```

### 6. GitHub Repository Settings

- GitHub Pages enabled (already automated!)
- Topics/tags (terraform, aws, infrastructure, etc.)
- About section with description and website link
- Social media card image (optional but nice)
- Discussions enabled (for community Q&A)
- Issues with templates
- Branch protection with required reviews

### 7. Updates to CODING_STANDARD.md

Proposed additions:

```markdown
* **README.md (required):**
- Header with module name and description
- Badge row with:
- Terraform Registry link
- Latest release version
- License
- Documentation (GitHub Pages link)
- Security scanning status
- Relevant AWS service badge
- "Why This Module?" section (differentiation)
- Features list
- Quick Start example
- Documentation links (to GitHub Pages)
- terraform-docs markers: `<!-- BEGIN_TF_DOCS -->` and `<!-- END_TF_DOCS -->`
- Links to Contributing and License

* **GitHub Pages Documentation (required for terraform_module):**
- Deployed via .github/workflows/docs.yml
- Built with MkDocs (Material theme)
- Minimum pages: index, getting-started, configuration
- Architecture diagrams where applicable
- Working examples with explanations

* **Repository Files (required):**
- LICENSE file (Apache 2.0 recommended)
- CHANGELOG.md (auto-generated via git-cliff)
- SECURITY.md (security policy)
- CONTRIBUTING.md (contribution guidelines)
- .github/workflows/release.yml (auto-create releases from tags)
- examples/ directory with working examples

* **Repository Configuration:**
- GitHub Pages enabled and deployed
- Topics/tags set (terraform, aws, relevant services)
- About section filled with website link
- Issue and PR templates configured
The release process must:
- Check that `git-cliff` and `bumpversion` are installed (with helpful install instructions on failure)
- Verify the current branch is `main` (refuse to release from other branches)
- Show the current and new version, then prompt for confirmation before proceeding
- Update `CHANGELOG.md` using `git cliff --unreleased --tag <version> --prepend CHANGELOG.md`
and commit it with a commit-msg compliant message (`chore: update CHANGELOG for <version>`)
- Bump the version using `bumpversion` with a compliant commit message
(`chore: bump version to <version>`)
- Print next steps (`git push && git push --tags`) but NOT push automatically

Use a shared `do_release` function for `release-patch`, `release-minor`, and `release-major`:

```makefile
# Internal function to handle version release
# Args: $(1) = major|minor|patch
define do_release
@echo "Checking if git-cliff is installed..."
@command -v git-cliff >/dev/null 2>&1 || { \
echo ""; \
echo "Error: git-cliff is not installed."; \
echo ""; \
echo "Please install it using one of the following methods:"; \
echo ""; \
echo " Cargo (Rust):"; \
echo " cargo install git-cliff"; \
echo ""; \
echo " Arch Linux:"; \
echo " pacman -S git-cliff"; \
echo ""; \
echo " Homebrew (macOS/Linux):"; \
echo " brew install git-cliff"; \
echo ""; \
echo " From binary (Linux/macOS/Windows):"; \
echo " https://github.com/orhun/git-cliff/releases"; \
echo ""; \
echo "For more installation options, see: https://git-cliff.org/docs/installation"; \
echo ""; \
exit 1; \
}
@echo "Checking if bumpversion is installed..."
@command -v bumpversion >/dev/null 2>&1 || { \
echo ""; \
echo "Error: bumpversion is not installed."; \
echo ""; \
echo "Please install it using:"; \
echo " make bootstrap"; \
echo ""; \
exit 1; \
}
@BRANCH=$$(git rev-parse --abbrev-ref HEAD); \
if [ "$$BRANCH" != "main" ]; then \
echo "Error: You must be on the 'main' branch to release."; \
echo "Current branch: $$BRANCH"; \
exit 1; \
fi; \
CURRENT=$$(grep ^current_version .bumpversion.cfg | head -1 | cut -d= -f2 | tr -d ' '); \
echo "Current version: $$CURRENT"; \
MAJOR=$$(echo $$CURRENT | cut -d. -f1); \
MINOR=$$(echo $$CURRENT | cut -d. -f2); \
PATCH=$$(echo $$CURRENT | cut -d. -f3); \
if [ "$(1)" = "major" ]; then \
NEW_VERSION=$$((MAJOR + 1)).0.0; \
elif [ "$(1)" = "minor" ]; then \
NEW_VERSION=$$MAJOR.$$((MINOR + 1)).0; \
elif [ "$(1)" = "patch" ]; then \
NEW_VERSION=$$MAJOR.$$MINOR.$$((PATCH + 1)); \
fi; \
echo "New version will be: $$NEW_VERSION"; \
printf "Continue? (y/n) "; \
read -r REPLY; \
case "$$REPLY" in \
[Yy]|[Yy][Ee][Ss]) \
echo "Updating CHANGELOG.md with git-cliff..."; \
git cliff --unreleased --tag $$NEW_VERSION --prepend CHANGELOG.md; \
git add CHANGELOG.md; \
git commit -m "chore: update CHANGELOG for $$NEW_VERSION"; \
echo "Bumping version with bumpversion..."; \
bumpversion --new-version $$NEW_VERSION \
--message "chore: bump version to {new_version}" patch; \
echo ""; \
echo "Released version $$NEW_VERSION"; \
echo ""; \
echo "Next steps:"; \
echo " git push && git push --tags"; \
;; \
*) \
echo "Release cancelled"; \
;; \
esac
endef

.PHONY: release-patch
release-patch: ## Release a patch version (x.x.PATCH)
$(call do_release,patch)

.PHONY: release-minor
release-minor: ## Release a minor version (x.MINOR.0)
$(call do_release,minor)

.PHONY: release-major
release-major: ## Release a major version (MAJOR.0.0)
$(call do_release,major)
```

## Reference Implementation

See [terraform-aws-actions-runner](https://github.com/infrahouse/terraform-aws-actions-runner) as the reference implementation:
- [Published Documentation](https://infrahouse.github.io/terraform-aws-actions-runner/)
- [Repository Page](https://github.com/infrahouse/terraform-aws-actions-runner)
## Implementation Plan

1. Enable GitHub Pages for all terraform_module repos (✅ automated via repos.tf)
2. Deploy docs.yml workflow to all modules (✅ automated)
3. Create baseline docs/index.md and mkdocs.yml where missing (✅ automated)
4. Deploy release.yml workflow to all modules (automate GitHub Release creation)
5. Create GitHub Project to track documentation completion
6. For each module:
- Update README.md with badges and structure
- Create comprehensive GitHub Pages documentation
- Add missing repository files (SECURITY.md, CONTRIBUTING.md, etc.)
- Set up proper GitHub repository settings
- Ensure working examples exist
- Verify release automation works
Loading