Skip to content

Commit

Permalink
feat: add variable for custom wiki directory separator
Browse files Browse the repository at this point in the history 
Introduces a new variable to allow users to specify a directory
separator character for generating wiki titles. This supports better
representation of module directory structures in GitHub wiki titles.
The default is set to a Unicode mathematical rising diagonal (⟋),
but users can choose from other options like '∕', '⁄', and '-'.

Updated the README to document this new feature and its usage.

Fixes #80
  • Loading branch information
@virgofx
virgofx committed Oct 27, 2024
1 parent 56c354e commit 511428b
Show file tree
Hide file tree
Showing 5 changed files with 236 additions and 66 deletions.
33 changes: 20 additions & 13 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,11 +8,13 @@ documentation.</b></sup>
![CI](https://github.com/techpivot/terraform-module-releaser/actions/workflows/ci.yml/badge.svg?event=pull_request)
[![Lint](https://github.com/techpivot/terraform-module-releaser/actions/workflows/lint.yml/badge.svg)][3]
[![CodeQL](https://github.com/techpivot/terraform-module-releaser/actions/workflows/codeql-analysis.yml/badge.svg)][4]
[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=techpivot_terraform-module-releaser&metric=alert_status)][5]

[1]: https://github.com/techpivot/terraform-module-releaser/releases/latest
[2]: https://github.com/marketplace/actions/terraform-module-releaser
[3]: https://github.com/techpivot/terraform-module-releaser/actions/workflows/lint.yml
[4]: https://github.com/techpivot/terraform-module-releaser/actions/workflows/codeql-analysis.yml
[5]: https://sonarcloud.io/summary/new_code?id=techpivot_terraform-module-releaser

Simplify the management of Terraform modules in your monorepo with this **GitHub Action**, designed to automate
module-specific versioning and releases. By streamlining the Terraform module release process, this action allows you to
Expand Down Expand Up @@ -115,6 +117,11 @@ jobs:
uses: techpivot/terraform-module-releaser@v1
```
This configuration provides an out-of-the-box solution that should work for most projects, as the defaults are
reasonably configured.
If you need to customize additional parameters, please refer to [Input Parameters](#input-parameters) section below.
## Permissions
Before executing the GitHub Actions workflow, ensure that you have the necessary permissions set for accessing pull
Expand Down Expand Up @@ -161,19 +168,19 @@ resources.
While the out-of-the-box defaults are suitable for most use cases, you can further customize the action's behavior by
configuring the following optional input parameters as needed.

| Input | Description | Default |
| -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- |
| `major-keywords` | Keywords in commit messages that indicate a major release | `major change,breaking change` |
| `minor-keywords` | Keywords in commit messages that indicate a minor release | `feat,feature` |
| `patch-keywords` | Keywords in commit messages that indicate a patch release | `fix,chore,docs` |
| `default-first-tag` | Specifies the default tag version | `v1.0.0` |
| `terraform-docs-version` | Specifies the terraform-docs version used to generate documentation for the wiki | `v0.19.0` |
| `delete-legacy-tags` | Specifies a boolean that determines whether tags and releases from Terraform modules that have been deleted should be automatically removed | `true` |
| `disable-wiki` | Whether to disable wiki generation for Terraform modules | `false` |
| `wiki-sidebar-changelog-max` | An integer that specifies how many changelog entries are displayed in the sidebar per module | `5` |
| `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` |
| `module-change-exclude-patterns` | A comma-separated list of file patterns to exclude from triggering version changes in Terraform modules. Patterns follow glob syntax (e.g., ".gitignore,_.md") and are relative to each Terraform module directory. Files matching these patterns will not affect version changes. **WARNING**: Avoid excluding '_.tf' files, as they are essential for module detection and versioning processes. | `".gitignore,*.md,*.tftest.hcl,tests/**"` |
| `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/**"` |
| Input | Description | Default |
| ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- |
| <code style="white-space:nowrap;">major-keywords</code> | Keywords in commit messages that indicate a major release | `major change,breaking change` |
| `minor-keywords` | Keywords in commit messages that indicate a minor release | `feat,feature` |
| `patch-keywords` | Keywords in commit messages that indicate a patch release | `fix,chore,docs` |
| `default-first-tag` | Specifies the default tag version | `v1.0.0` |
| `terraform-docs-version` | Specifies the terraform-docs version used to generate documentation for the wiki | `v0.19.0` |
| `delete-legacy-tags` | Specifies a boolean that determines whether tags and releases from Terraform modules that have been deleted should be automatically removed | `true` |
| `disable-wiki` | Whether to disable wiki generation for Terraform modules | `false` |
| `wiki-sidebar-changelog-max` | An integer that specifies how many changelog entries are displayed in the sidebar per module | `5` |
| `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` |
| `module-change-exclude-patterns` | <h6 style="margin:0">A comma-separated list of file patterns to exclude from triggering version changes in Terraform modules. Patterns follow glob syntax (e.g., ".gitignore,_.md") and are relative to each Terraform module directory. Files matching these patterns will not affect version changes. **WARNING**: Avoid excluding '_.tf' files, as they are essential for module detection and versioning processes.</h6> | `".gitignore,*.md,*.tftest.hcl,tests/**"` |
| `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/**"` |

### Example Usage with Inputs

Expand Down
38 changes: 38 additions & 0 deletions src/constants.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,3 +9,41 @@ export const BRANDING_COMMENT =

export const BRANDING_WIKI =
'<h4 align="center">Powered by <img src="https://raw.githubusercontent.com/techpivot/terraform-module-releaser/refs/heads/main/assets/github-mark-12x14.png" height="14" width="12" align="top" /> <a href="https://github.com/techpivot/terraform-module-releaser">techpivot/terraform-module-releaser</a></h4>';

/**
* WIKI_TITLE_REPLACEMENTS - This object maps specific characters in wiki titles to visually
* similar Unicode alternatives to handle GitHub Wiki limitations related to directory structure,
* uniqueness, and consistent character visibility.
*
* ### GitHub Wiki Issues Addressed:
*
* - **Slash (`/`) Handling**:
* GitHub Wiki does not interpret forward slashes (`/`) as part of a directory structure in titles.
* When a title includes a slash, GitHub Wiki only recognizes the last segment (basename) for
* navigation, leading to potential conflicts if multiple pages share the same basename but
* reside in different contexts. By replacing `/` with a visually similar division slash (`∕`),
* this mapping helps preserve the intended path within the title, avoiding structure-related conflicts.
*
* - **Hyphen (`-`) Display in Sub-Directories**:
* GitHub Wiki exhibits inconsistent display behavior for hyphens when files are saved within
* subdirectories. If a file is created or saved with a hyphen in a subdirectory (e.g., `__generated`),
* the hyphen does not display properly. Upon saving, GitHub may automatically move the file to
* the root directory, overriding the subdirectory placement. To circumvent this issue, all wiki files
* are saved at the root level, allowing the standard hyphen (`-`) to be used effectively for naming
* without display issues or reorganization by GitHub.
*
* ### Key-Value Pairs:
* - Each **key** represents an original character in the title that may be problematic in GitHub Wiki.
* - Each **value** is a Unicode replacement character chosen to visually resemble the original while
* avoiding structural or display conflicts.
*
* ### Current Mappings:
* - `'/'` → `'∕'` (U+2215 Division Slash): Replaces forward slashes in titles to prevent directory
* conflicts.
* - (Optional) `'-'` → `'‒'` (U+2012 Figure Dash): This mapping may be applied if files are required
* in a subdirectory, but currently, it is unnecessary as files are saved at the root.
*/
export const WIKI_TITLE_REPLACEMENTS: { [key: string]: string } = {
'/': '∕', // Replace forward slash with a visually similar division slash (U+2215)
// '-': '‒', // Replace hyphen with figure dash (U+2012) for better root display (optional)
};
50 changes: 50 additions & 0 deletions src/file-util.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -52,3 +52,53 @@ export function copyModuleContents(directory: string, tmpDir: string, baseDirect
}
}
}

/**
* Removes all contents of a specified directory except for specified items to preserve.
*
* @param directory - The path of the directory to clear.
* @param exceptions - An array of filenames or directory names to preserve within the directory.
*
* This function removes all files and subdirectories within the specified directory while
* retaining any items listed in the `exceptions` array. The names in `exceptions` should be
* relative to the `directory` (e.g., `['.git', 'README.md']`), referring to items within the
* directory you want to keep.
*
* ### Example Usage:
*
* Suppose you have a directory structure:
* ```
* /example-directory/
* ├── .git/
* ├── config.json
* ├── temp/
* └── README.md
* ```
*
* Using `removeDirectoryContents('/example-directory', ['.git', 'README.md'])` will:
* - Remove `config.json` and the `temp` folder.
* - Preserve the `.git` directory and `README.md` file within `/example-directory`.
*
* **Note:**
* - Items in `exceptions` are matched only by their names relative to the given `directory`.
* - If the `.git` directory or `README.md` file were in a nested subdirectory within `/example-directory`,
* you would need to adjust the `exceptions` parameter accordingly to reflect the correct relative path.
*
* @example
* removeDirectoryContents('/home/user/project', ['.git', 'important-file.txt']);
* // This would remove all contents inside `/home/user/project`, except for the `.git` directory
* // and the `important-file.txt` file.
*/
export function removeDirectoryContents(directory: string, exceptions: string[] = []): void {
if (fs.existsSync(directory)) {
for (const item of fs.readdirSync(directory)) {
const itemPath = path.join(directory, item);

// Skip removal for items listed in the exceptions array
if (!exceptions.includes(item)) {
fs.rmSync(itemPath, { recursive: true, force: true });
}
}
info(`Removed contents of directory [${directory}], preserving items: ${exceptions.join(', ')}`);
}
}
Loading

0 comments on commit 511428b

Please sign in to comment.