René's URL Explorer Experiment

{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"🩹 [Patch]: Only create releases when significant changes are detected (module and documentation)","articleBody":"### Describe the change\n\nToday, both modules and documentation are published with a version bump whenever a PR is merged, irrespective of the files being changed. We should ensure that we only publish new versions when there are significant changes to the relevant source files.\n\n### Problem Statement\n\nCurrently, every merged PR triggers releases for both module and documentation, even when:\n- Only CI/CD configuration files are changed (e.g., workflow files, linter configs)\n- Only repository metadata files are changed (e.g., README badges, CODEOWNERS)\n- Changes are made to unrelated parts of the repository\n- Whitespace-only or formatting-only changes occur in non-source files\n\nThis results in:\n- Version number inflation without meaningful changes for consumers\n- Unnecessary churn in the PowerShell Gallery and documentation site\n- Confusion for users tracking module and documentation updates\n- Increased noise in release notifications\n\n### Expected Behavior\n\n#### 1. Module Release Trigger Conditions\n\nThe workflow SHOULD only create a new **module release** when the PR includes changes to files that affect the module's functionality:\n\n**Files that SHOULD trigger a module release:**\n- Source code files in `src/` directory (functions, classes, variables, etc.)\n- Module manifest changes affecting exported members or metadata\n- Data files included in the module (e.g., JSON schemas, configuration templates)\n- Type and format files (`.ps1xml`)\n- Assembly files in the module\n- Any file that ends up in the built module artifact\n\n**Files that SHOULD NOT trigger a module release:**\n- CI/CD workflow files (`.github/workflows/`)\n- Linter and tool configuration files (`.github/linters/`, `.editorconfig`)\n- Repository metadata (`.github/CODEOWNERS`, `CONTRIBUTING.md`)\n- Test files in `tests/` directory\n- Example files in `examples/` directory (unless shipped with module)\n- Documentation source files (if not shipped with module)\n- Build scripts and development tools\n- Git-related files (`.gitignore`, `.gitattributes`)\n\n#### 2. Documentation Publish Trigger Conditions\n\nThe workflow SHOULD only publish new **documentation** when the PR includes changes to files that affect the documentation output:\n\n**Files that SHOULD trigger a documentation publish:**\n- Source code files in `src/` (changes affect auto-generated function docs)\n- Documentation configuration (`mkdocs.yml`)\n- Custom documentation content in `docs/` directory\n- README.md (if used as documentation landing page)\n- About help topics and inline documentation in source\n- Any file that contributes to the generated documentation site\n\n**Files that SHOULD NOT trigger a documentation publish:**\n- CI/CD workflow files (`.github/workflows/`)\n- Linter and tool configuration files\n- Test files in `tests/` directory\n- Git-related files\n- Files unrelated to module functionality or documentation\n\n#### 3. Combined Change Detection\n\nWhen a PR contains mixed changes:\n- If module source files changed → Trigger module release\n- If documentation-relevant files changed → Trigger documentation publish\n- If both types changed → Trigger both\n- If neither type changed → Skip both release steps\n\n#### 4. Version Bump Behavior\n\nWhen a release IS triggered, the version bump behavior should remain as-is:\n- `Patch` label or default → Patch version bump\n- `Minor` label → Minor version bump  \n- `Major` label → Major version bump\n\nWhen NO significant changes are detected for a particular artifact:\n- The release/publish step for that artifact SHOULD be skipped\n- Build and test steps SHOULD still run normally\n- A clear indication SHOULD be provided in the workflow summary (e.g., \"Module release skipped: no significant module changes detected\")\n\n#### 5. Configuration Options\n\nUsers SHOULD be able to customize the behavior via `.github/PSModule.yml`:\n\n- Define additional paths that should trigger module releases\n- Define additional paths that should trigger documentation publishes\n- Define paths that should be excluded from consideration\n- Option to force release behavior (always release on merge, or respect change detection)\n\n#### 6. Edge Cases\n\n- **First release**: If no previous release exists, any change should trigger a release\n- **Force release**: Users should be able to force a release via PR label or commit message convention (e.g., `[force-release]`)\n- **Multiple modules in repo**: Change detection should be scoped to the specific module being processed\n- **Submodule changes**: Changes to git submodules pointing to module content should trigger releases\n\n### User Scenarios\n\n1. **Scenario: CI-only change**\n   - Given a PR that only modifies `.github/workflows/workflow.yml`\n   - When the PR is merged to main\n   - Then NO module release should be created\n   - And NO documentation should be published\n   - And the workflow summary should indicate both were skipped due to no significant changes\n\n2. **Scenario: Source code change**\n   - Given a PR that modifies `src/functions/public/Get-Something.ps1`\n   - When the PR is merged to main\n   - Then a new module release SHOULD be created\n   - And new documentation SHOULD be published (function docs updated)\n\n3. **Scenario: Documentation-only change**\n   - Given a PR that only modifies `docs/getting-started.md`\n   - When the PR is merged to main\n   - Then NO module release should be created\n   - And new documentation SHOULD be published\n\n4. **Scenario: Test-only change**\n   - Given a PR that only adds new test cases in `tests/`\n   - When the PR is merged to main\n   - Then NO module release should be created\n   - And NO documentation should be published\n\n5. **Scenario: mkdocs.yml change**\n   - Given a PR that only modifies `mkdocs.yml` (navigation, theme, etc.)\n   - When the PR is merged to main\n   - Then NO module release should be created\n   - And new documentation SHOULD be published\n\n### Inspiration\n\n- https://powershellexplained.com/2017-10-14-Powershell-module-semantic-version/\n- Semantic release tools in other ecosystems use similar path-based filtering","author":{"url":"https://github.com/MariusStorhaug","@type":"Person","name":"MariusStorhaug"},"datePublished":"2025-08-27T06:26:57.000Z","interactionStatistic":{"@type":"InteractionCounter","interactionType":"https://schema.org/CommentAction","userInteractionCount":0},"url":"https://github.com/184/Process-PSModule/issues/184"}