KeepAChangelog

0.3.0

en-US/KeepAChangelog-Help.xml

<?xml version="1.0" encoding="utf-8"?>
<helpItems xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" schema="maml" xmlns="http://msh">
  <command:command>
    <command:details>
      <command:name>Convert-ChangelogReleaseNotesToTagMessage</command:name>
      <maml:description>
        <maml:para>Converts markdown release notes to plain text.</maml:para>
      </maml:description>
      <command:verb>Convert</command:verb>
      <command:noun>ChangelogReleaseNotesToTagMessage</command:noun>
    </command:details>
    <maml:description>
      <maml:para>`Convert-ChangelogReleaseNotesToTagMessage` simplifies markdown release notes for tag messages.</maml:para>
      <maml:para>The command:</maml:para>
      <maml:para>- turns `###` headings into plain section names - turns markdown bullets into plain lines - collapses repeated blank lines - trims the final result</maml:para>
    </maml:description>
    <command:syntax>
      <command:syntaxItem>
        <maml:name>PS&gt;</maml:name>
      </command:syntaxItem>
    </command:syntax>
    <command:parameters />
    <command:inputTypes />
    <command:returnValues />
    <maml:alertSet>
      <maml:alert>
        <maml:para />
      </maml:alert>
    </maml:alertSet>
    <command:examples>
      <command:example>
        <maml:title>--------- EXAMPLE 1 ---------</maml:title>
        <maml:introduction>
          <maml:para>```text
PS&gt; Convert-ChangelogReleaseNotesToTagMessage -ReleaseNotes "### Fixed`n`n- Fixed CLI parsing."
```</maml:para>
          <maml:para>&#x80;</maml:para>
          <maml:para>Returns:</maml:para>
          <maml:para>&#x80;</maml:para>
          <maml:para>```text
Fixed</maml:para>
          <maml:para>&#x80;</maml:para>
          <maml:para>Fixed CLI parsing.
```</maml:para>
        </maml:introduction>
        <dev:code />
        <dev:remarks />
      </command:example>
    </command:examples>
    <command:relatedLinks>
      <maml:navigationLink>
        <maml:linkText>Online Version</maml:linkText>
        <command:uri />
      </maml:navigationLink>
    </command:relatedLinks>
  </command:command>
  <command:command>
    <command:details>
      <command:name>Get-KeepAChangelogVersion</command:name>
      <maml:description>
        <maml:para>Returns the loaded KeepAChangelog module version.</maml:para>
      </maml:description>
      <command:verb>Get</command:verb>
      <command:noun>KeepAChangelogVersion</command:noun>
    </command:details>
    <maml:description>
      <maml:para>`Get-KeepAChangelogVersion` returns the version of the currently loaded `KeepAChangelog` module.</maml:para>
      <maml:para>Use it in CI logs or local troubleshooting when you need to confirm which module version produced a release or validation result.</maml:para>
    </maml:description>
    <command:syntax>
      <command:syntaxItem>
        <maml:name>PS&gt;</maml:name>
      </command:syntaxItem>
    </command:syntax>
    <command:parameters />
    <command:inputTypes />
    <command:returnValues />
    <maml:alertSet>
      <maml:alert>
        <maml:para />
      </maml:alert>
    </maml:alertSet>
    <command:examples>
      <command:example>
        <maml:title>--------- EXAMPLE 1 ---------</maml:title>
        <maml:introduction>
          <maml:para>```text
PS&gt; Get-KeepAChangelogVersion
```</maml:para>
          <maml:para>&#x80;</maml:para>
          <maml:para>Returns the version string for the loaded `KeepAChangelog` module.</maml:para>
        </maml:introduction>
        <dev:code />
        <dev:remarks />
      </command:example>
    </command:examples>
    <command:relatedLinks>
      <maml:navigationLink>
        <maml:linkText>Online Version</maml:linkText>
        <command:uri />
      </maml:navigationLink>
    </command:relatedLinks>
  </command:command>
  <command:command>
    <command:details>
      <command:name>Initialize-KeepAChangelogFile</command:name>
      <maml:description>
        <maml:para>Initializes a Keep a Changelog template.</maml:para>
      </maml:description>
      <command:verb>Initialize</command:verb>
      <command:noun>KeepAChangelogFile</command:noun>
    </command:details>
    <maml:description>
      <maml:para>`Initialize-KeepAChangelogFile` writes a markdown changelog template with:</maml:para>
      <maml:para>- the standard introduction text - a `## [Unreleased]` section - default subsection headings - a footer `[Unreleased]` compare link when `-PreviousReleaseReference` is provided</maml:para>
      <maml:para>Use `-Force` when you want to overwrite an existing file.</maml:para>
      <maml:para>When new footer links must be generated:</maml:para>
      <maml:para>- GitHub uses `/compare/&lt;previous&gt;...HEAD` - GitLab uses `/-/compare/&lt;previous&gt;...HEAD` - Azure DevOps uses `/branchCompare?baseVersion=&lt;previous&gt;&amp;targetVersion=&lt;target&gt;&amp;_a=commits`</maml:para>
      <maml:para>Use `-RepositoryProvider` when the repository host alone is not enough to identify the provider, and use `-RepositoryTargetReference` for Azure DevOps target refs such as `GBmain` or `GBdevelop`.</maml:para>
    </maml:description>
    <command:syntax>
      <command:syntaxItem>
        <maml:name>PS&gt;</maml:name>
      </command:syntaxItem>
    </command:syntax>
    <command:parameters />
    <command:inputTypes />
    <command:returnValues />
    <maml:alertSet>
      <maml:alert>
        <maml:para />
      </maml:alert>
    </maml:alertSet>
    <command:examples>
      <command:example>
        <maml:title>--------- EXAMPLE 1 ---------</maml:title>
        <maml:introduction>
          <maml:para>```text
PS&gt; Initialize-KeepAChangelogFile -Path ./CHANGELOG.md -RepositoryUrl https://github.com/couragedk/KeepAChangelog -PreviousReleaseReference develop
```</maml:para>
          <maml:para>&#x80;</maml:para>
          <maml:para>Creates `CHANGELOG.md` with an `[Unreleased]` compare link that starts from `develop`.</maml:para>
        </maml:introduction>
        <dev:code />
        <dev:remarks />
      </command:example>
      <command:example>
        <maml:title>--------- EXAMPLE 2 ---------</maml:title>
        <maml:introduction>
          <maml:para>```text
PS&gt; Initialize-KeepAChangelogFile -Path ./CHANGELOG.md -RepositoryUrl https://code.example.com/group/project -RepositoryProvider GitLab -PreviousReleaseReference 1.5.2
```</maml:para>
          <maml:para>&#x80;</maml:para>
          <maml:para>Creates a changelog for a self-hosted GitLab repository by using the explicit provider hint.</maml:para>
        </maml:introduction>
        <dev:code />
        <dev:remarks />
      </command:example>
      <command:example>
        <maml:title>--------- EXAMPLE 3 ---------</maml:title>
        <maml:introduction>
          <maml:para>```text
PS&gt; Initialize-KeepAChangelogFile -Path ./CHANGELOG.md -RepositoryUrl https://ado.example.com/Org/Project/_git/Tools -RepositoryProvider AzureDevOps -RepositoryTargetReference GBdevelop -PreviousReleaseReference GTv1.5.2
```</maml:para>
          <maml:para>&#x80;</maml:para>
          <maml:para>Creates a changelog for Azure DevOps by using the supplied release reference as `baseVersion` and the target ref as `targetVersion`.</maml:para>
        </maml:introduction>
        <dev:code />
        <dev:remarks />
      </command:example>
    </command:examples>
    <command:relatedLinks>
      <maml:navigationLink>
        <maml:linkText>Online Version</maml:linkText>
        <command:uri />
      </maml:navigationLink>
    </command:relatedLinks>
  </command:command>
  <command:command>
    <command:details>
      <command:name>Move-UnreleasedChangelog</command:name>
      <maml:description>
        <maml:para>Moves `Unreleased` notes into a versioned release section.</maml:para>
      </maml:description>
      <command:verb>Move</command:verb>
      <command:noun>UnreleasedChangelog</command:noun>
    </command:details>
    <maml:description>
      <maml:para>`Move-UnreleasedChangelog` treats `## [Unreleased]` as the source section for the next release.</maml:para>
      <maml:para>The command:</maml:para>
      <maml:para>1. reads the current unreleased content 2. removes empty `###` subsections from the new release notes 3. inserts `## [&lt;version&gt;] - &lt;date&gt;` below `## [Unreleased]` 4. clears `Unreleased` while keeping subsection headings 5. updates the `[Unreleased]` compare link when a reference-link footer exists or `-RepositoryUrl` is supplied 6. adds or updates the `[&lt;version&gt;]` release link from the previous release reference to the new release reference when footer links are being maintained</maml:para>
      <maml:para>`-Version` is required. `-Date` is optional. When `-Date` is omitted, the current date is used. When `-Date` is provided, it must use `yyyy-MM-dd` format.</maml:para>
      <maml:para>If the changelog has no footer and you want footer links to be created or maintained, pass `-RepositoryUrl`. If you omit it, the release move still runs and the changelog stays without footer links.</maml:para>
      <maml:para>When new footer links must be generated:</maml:para>
      <maml:para>- GitHub uses `/compare/&lt;previous&gt;...HEAD` and `/releases/tag/&lt;release&gt;` - GitLab uses `/-/compare/&lt;previous&gt;...HEAD` and `/-/tags/&lt;release&gt;` - Azure DevOps uses `/branchCompare?baseVersion=&lt;previous&gt;&amp;targetVersion=&lt;target&gt;&amp;_a=commits`</maml:para>
      <maml:para>The returned object also includes `KeepAChangelogVersion` so CI logs and troubleshooting output can show which module version produced the release data.</maml:para>
    </maml:description>
    <command:syntax>
      <command:syntaxItem>
        <maml:name>PS&gt;</maml:name>
      </command:syntaxItem>
    </command:syntax>
    <command:parameters />
    <command:inputTypes />
    <command:returnValues />
    <maml:alertSet>
      <maml:alert>
        <maml:para />
      </maml:alert>
    </maml:alertSet>
    <command:examples>
      <command:example>
        <maml:title>--------- EXAMPLE 1 ---------</maml:title>
        <maml:introduction>
          <maml:para>```text
PS&gt; Move-UnreleasedChangelog -Path ./CHANGELOG.md -Version 1.6.0 -Date 2026-04-30
```</maml:para>
          <maml:para>&#x80;</maml:para>
          <maml:para>Promotes the current unreleased notes into release `1.6.0`.</maml:para>
        </maml:introduction>
        <dev:code />
        <dev:remarks />
      </command:example>
      <command:example>
        <maml:title>--------- EXAMPLE 2 ---------</maml:title>
        <maml:introduction>
          <maml:para>```text
PS&gt; Move-UnreleasedChangelog -Path ./CHANGELOG.md -Version 1.0.0 -RepositoryUrl https://code.example.com/group/project -RepositoryProvider GitLab
```</maml:para>
          <maml:para>&#x80;</maml:para>
          <maml:para>Creates the first release and adds GitLab footer links for a self-hosted GitLab repository.</maml:para>
        </maml:introduction>
        <dev:code />
        <dev:remarks />
      </command:example>
      <command:example>
        <maml:title>--------- EXAMPLE 3 ---------</maml:title>
        <maml:introduction>
          <maml:para>```text
PS&gt; Move-UnreleasedChangelog -Path ./CHANGELOG.md -Version 13.0.4 -RepositoryUrl https://ado.example.com/Org/Project/_git/Tools -RepositoryProvider AzureDevOps -RepositoryTargetReference GBdevelop -ReleaseReference GTv13.0.4
```</maml:para>
          <maml:para>&#x80;</maml:para>
          <maml:para>Creates Azure DevOps footer links by using `GTv13.0.4` as the release ref and `GBdevelop` as the ongoing unreleased target ref.</maml:para>
        </maml:introduction>
        <dev:code />
        <dev:remarks />
      </command:example>
    </command:examples>
    <command:relatedLinks>
      <maml:navigationLink>
        <maml:linkText>Online Version</maml:linkText>
        <command:uri />
      </maml:navigationLink>
    </command:relatedLinks>
  </command:command>
  <command:command>
    <command:details>
      <command:name>Test-KeepAChangelogFile</command:name>
      <maml:description>
        <maml:para>Validates a Keep a Changelog file.</maml:para>
      </maml:description>
      <command:verb>Test</command:verb>
      <command:noun>KeepAChangelogFile</command:noun>
    </command:details>
    <maml:description>
      <maml:para>`Test-KeepAChangelogFile` reads a changelog and validates:</maml:para>
      <maml:para>- the presence of `## [Unreleased]` - the `[Unreleased]` compare link when a reference-link footer is present, even if blank lines separate the footer links - GitHub `/compare/`, GitLab `/-/compare/`, and Azure DevOps `branchCompare?baseVersion=...&amp;targetVersion=...&amp;_a=commits` footer-link formats - versioned release headings in `## [&lt;version&gt;] - &lt;date&gt;` format - duplicate reference-link labels</maml:para>
      <maml:para>It returns a result object with `IsValid`, `Errors`, and extracted compare-link values.</maml:para>
    </maml:description>
    <command:syntax>
      <command:syntaxItem>
        <maml:name>PS&gt;</maml:name>
      </command:syntaxItem>
    </command:syntax>
    <command:parameters />
    <command:inputTypes />
    <command:returnValues />
    <maml:alertSet>
      <maml:alert>
        <maml:para />
      </maml:alert>
    </maml:alertSet>
    <command:examples>
      <command:example>
        <maml:title>--------- EXAMPLE 1 ---------</maml:title>
        <maml:introduction>
          <maml:para>```text
PS&gt; Test-KeepAChangelogFile -Path ./CHANGELOG.md
```</maml:para>
          <maml:para>&#x80;</maml:para>
          <maml:para>Returns the validation result for the current changelog file.</maml:para>
        </maml:introduction>
        <dev:code />
        <dev:remarks />
      </command:example>
    </command:examples>
    <command:relatedLinks>
      <maml:navigationLink>
        <maml:linkText>Online Version</maml:linkText>
        <command:uri />
      </maml:navigationLink>
    </command:relatedLinks>
  </command:command>
</helpItems>