Skip to content

Commit f02d448

Browse files
polleuretanpolleuretan
authored
feat: custom wiki usage block (#235)
* Add wiki-custom-usage-string setting * Use config.wikiCustomUsageString in the wiki generation logic * Extract default usage block into a separate function * A couple of test cases to check the new logic of "usage" block generation * Mention wiki-custom-usage-string in the README * Fix linter errors * Replace wiki-custom-usage-string with wiki-custom-usage-template in config and readme * New method to get the version number without "v" * Add new module to handle template rendering * Use newly defined render function for the wiki generation * Tests for new templated "usage" block genration * Update README * Update config name and default value in action.yaml * Drop DEFAULT_USAGE_BLOCK function and use just render helper * Rename wikiCustomUsageTemplate -> wikiUsageTemplate in existing tests * Add new variables to the test case * Linter feedback * Use `key in variables` to make sure the key is present * Add default wiki usage template to test mocks
1 parent 5fb1bb4 commit f02d448

File tree

10 files changed

+231
-24
lines changed

10 files changed

+231
-24
lines changed

‎README.md

Lines changed: 48 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -184,21 +184,22 @@ resources.
184184
While the out-of-the-box defaults are suitable for most use cases, you can further customize the action's behavior by
185185
configuring the following optional input parameters as needed.
186186

187-
| Input | Description | Default |
188-
| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- |
189-
| `major-keywords` | Keywords in commit messages that indicate a major release | `major change,breaking change` |
190-
| `minor-keywords` | Keywords in commit messages that indicate a minor release | `feat,feature` |
191-
| `patch-keywords` | Keywords in commit messages that indicate a patch release | `fix,chore,docs` |
192-
| `default-first-tag` | Specifies the default tag version | `v1.0.0` |
193-
| `terraform-docs-version` | Specifies the terraform-docs version used to generate documentation for the wiki | `v0.19.0` |
194-
| `delete-legacy-tags` | Specifies a boolean that determines whether tags and releases from Terraform modules that have been deleted should be automatically removed | `true` |
195-
| `disable-wiki` | Whether to disable wiki generation for Terraform modules | `false` |
196-
| `wiki-sidebar-changelog-max` | An integer that specifies how many changelog entries are displayed in the sidebar per module | `5` |
197-
| `disable-branding` | Controls whether a small branding link to the action's repository is added to PR comments. Recommended to leave enabled to support OSS. | `false` |
198-
| `module-path-ignore` | Comma-separated list of module paths to completely ignore. Modules matching any pattern here are excluded from all versioning, releases, and documentation.<br><sub>[Read more here](#understanding-the-filtering-options)</sub> | `` (empty string) |
199-
| `module-change-exclude-patterns` | Comma-separated list of file patterns (relative to each module) to exclude from triggering version changes. Lets you release a module but control which files inside it do not force a version bump.<br><sub>[Read more here](#understanding-the-filtering-options)</sub> | `.gitignore,*.md,*.tftest.hcl,tests/**` |
200-
| `module-asset-exclude-patterns` | A comma-separated list of file patterns to exclude when bundling a Terraform module for tag/release. Patterns follow glob syntax (e.g., `tests/\*\*`) and are relative to each Terraform module directory. Files matching these patterns will be excluded from the bundled output. | `.gitignore,*.md,*.tftest.hcl,tests/**` |
201-
| `use-ssh-source-format` | If enabled, all links to source code in generated Wiki documentation will use SSH standard format (e.g., `git::ssh://[email protected]/owner/repo.git`) instead of HTTPS format (`git::https://github.com/owner/repo.git`) | `false` |
187+
| Input | Description | Default |
188+
| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
189+
| `major-keywords` | Keywords in commit messages that indicate a major release | `major change,breaking change` |
190+
| `minor-keywords` | Keywords in commit messages that indicate a minor release | `feat,feature` |
191+
| `patch-keywords` | Keywords in commit messages that indicate a patch release | `fix,chore,docs` |
192+
| `default-first-tag` | Specifies the default tag version | `v1.0.0` |
193+
| `terraform-docs-version` | Specifies the terraform-docs version used to generate documentation for the wiki | `v0.19.0` |
194+
| `delete-legacy-tags` | Specifies a boolean that determines whether tags and releases from Terraform modules that have been deleted should be automatically removed | `true` |
195+
| `disable-wiki` | Whether to disable wiki generation for Terraform modules | `false` |
196+
| `wiki-sidebar-changelog-max` | An integer that specifies how many changelog entries are displayed in the sidebar per module | `5` |
197+
| `disable-branding` | Controls whether a small branding link to the action's repository is added to PR comments. Recommended to leave enabled to support OSS. | `false` |
198+
| `module-path-ignore` | Comma-separated list of module paths to completely ignore. Modules matching any pattern here are excluded from all versioning, releases, and documentation.<br><sub>[Read more here](#understanding-the-filtering-options)</sub> | `` (empty string) |
199+
| `module-change-exclude-patterns` | Comma-separated list of file patterns (relative to each module) to exclude from triggering version changes. Lets you release a module but control which files inside it do not force a version bump.<br><sub>[Read more here](#understanding-the-filtering-options)</sub> | `.gitignore,*.md,*.tftest.hcl,tests/**` |
200+
| `module-asset-exclude-patterns` | A comma-separated list of file patterns to exclude when bundling a Terraform module for tag/release. Patterns follow glob syntax (e.g., `tests/\*\*`) and are relative to each Terraform module directory. Files matching these patterns will be excluded from the bundled output. | `.gitignore,*.md,*.tftest.hcl,tests/**` |
201+
| `use-ssh-source-format` | If enabled, all links to source code in generated Wiki documentation will use SSH standard format (e.g., `git::ssh://[email protected]/owner/repo.git`) instead of HTTPS format (`git::https://github.com/owner/repo.git`) | `false` |
202+
| `wiki-usage-template` | A raw, multi-line string to override the default 'Usage' section in the generated wiki. Allows using variables like {{module_name}}, {{latest_tag}}, {{latest_tag_version_number}} and more.<br><sub>[Read more here](#configuring-the-usage-template)</sub> | [See action.yml](https://github.com/polleuretan/terraform-module-releaser/blob/main/action.yml#L108) |
202203

203204
### Understanding the filtering options
204205

@@ -281,9 +282,22 @@ similar to those used in `.gitignore` files. For more details on the pattern mat
281282
[source code](https://github.com/techpivot/terraform-module-releaser/blob/main/src/utils/file.ts) or visit the
282283
[minimatch documentation](https://github.com/isaacs/minimatch).
283284

285+
### Configuring the Usage Template
286+
287+
The `wiki-usage-template` input allows you to customize the "Usage" section of the generated wiki page for each module.
288+
You can use the following dynamic variables in your template:
289+
290+
| Variable | Description | Example |
291+
| ------------------------------- | ------------------------------------------------------------------------------------------------- | ---------------------------------------- |
292+
| `{{module_name}}` | The name of the module. | `aws/s3-bucket` |
293+
| `{{latest_tag}}` | The latest Git tag for the module. | `aws/s3-bucket/v1.2.3` |
294+
| `{{latest_tag_version_number}}` | The version number of the latest tag. | `1.2.3` |
295+
| `{{module_source}}` | The Git source URL for the module, respecting the `use-ssh-source-format` input. | `git::https://github.com/owner/repo.git` |
296+
| `{{module_name_terraform}}` | A Terraform-safe version of the module name (e.g., special characters replaced with underscores). | `aws_s3_bucket` |
297+
284298
### Example Usage with Inputs
285299

286-
```yml
300+
````yml
287301
name: Terraform Module Releaser
288302
on:
289303
pull_request:
@@ -317,7 +331,24 @@ jobs:
317331
module-change-exclude-patterns: .gitignore,*.md,docs/**,examples/**,*.tftest.hcl,tests/**
318332
module-asset-exclude-patterns: .gitignore,*.md,*.tftest.hcl,tests/**
319333
use-ssh-source-format: false
320-
```
334+
wiki-usage-template: |
335+
# My Custom Usage Instructions
336+
337+
This is a custom usage block.
338+
339+
You can add any markdown you want here.
340+
341+
And use variables like {{module_name}}, {{latest_tag}}, {{latest_tag_version_number}},
342+
{{module_source}} and {{module_name_terraform}}.
343+
344+
```hcl
345+
module "{{module_name_terraform}}" {
346+
source = "{{module_source}}?ref={{latest_tag}}"
347+
version = "{{latest_tag_version_number}}"
348+
# ...
349+
}
350+
```
351+
````
321352

322353
## Outputs
323354

‎__mocks__/config.ts

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,17 @@ const defaultConfig: Config = {
2626
moduleAssetExcludePatterns: ['tests/**', 'examples/**'],
2727
githubToken: 'ghp_test_token_2c6912E7710c838347Ae178B4',
2828
useSSHSourceFormat: false,
29+
wikiUsageTemplate: `
30+
To use this module in your Terraform, refer to the below module example:
31+
32+
\`\`\`hcl
33+
module "{{module_name_terraform}}" {
34+
source = "git::{{module_source}}?ref={{latest_tag}}"
35+
36+
# See inputs below for additional required parameters
37+
}
38+
\`\`\`
39+
`
2940
};
3041

3142
/**

‎__tests__/templating.test.ts

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
import { describe, it, expect } from 'vitest';
2+
import { render } from '../src/templating';
3+
4+
describe('templating', () => {
5+
it('should replace a single placeholder', () => {
6+
const template = 'Hello, {{name}}!';
7+
const variables = { name: 'World' };
8+
const result = render(template, variables);
9+
expect(result).toBe('Hello, World!');
10+
});
11+
12+
it('should replace multiple placeholders', () => {
13+
const template = '{{greeting}}, {{name}}!';
14+
const variables = { greeting: 'Hi', name: 'There' };
15+
const result = render(template, variables);
16+
expect(result).toBe('Hi, There!');
17+
});
18+
19+
it('should handle templates with no placeholders', () => {
20+
const template = 'Just a plain string.';
21+
const variables = { name: 'World' };
22+
const result = render(template, variables);
23+
expect(result).toBe('Just a plain string.');
24+
});
25+
26+
it('should handle empty string values', () => {
27+
const template = 'A{{key}}B';
28+
const variables = { key: '' };
29+
const result = render(template, variables);
30+
expect(result).toBe('AB');
31+
});
32+
33+
it('should leave unmapped placeholders untouched', () => {
34+
const template = 'Hello, {{name}} and {{unmapped}}!';
35+
const variables = { name: 'World' };
36+
const result = render(template, variables);
37+
expect(result).toBe('Hello, World and {{unmapped}}!');
38+
});
39+
});

0 commit comments

Comments
 (0)