diff --git a/README.md b/README.md index a5d3ae2..e76411b 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,7 @@ A project for managing repository releases, such as [GitHub releases](https://do ## Introduction -This project provides CI templates and scripts that other projects can utilize for managing releases. +This project provides CI templates, scripts, and cmdlets that other projects can utilize for generating release notes and creating releases. ### Main project structure @@ -86,21 +86,23 @@ git tag v1.0.12-alpha git tag v1.0.12-beta.1 ``` -#### Releases +#### Creating releases The entrypoint script [`Invoke-Release.ps1`](src/scripts/ci/Invoke-Release.ps1) can be used to create or simulate the creation of releases for GitHub repositories. Simply specify the relevant values pertaining to the release, and if desired, the path to the file containing the release notes to include with it. -### Continuous Integration +### Continuous Integration (CI) -The included CI files use a very similar set of [entrypoint scripts](src/scripts/ci) to the development versions to run the very same steps of generating release notes and creating releases. +The project provides a set of [entrypoint scripts](src/scripts/ci) for executing the very same steps for generating release notes and creating releases in CI environments. -#### Generating release notes +#### via Templates + +##### Generating release notes To generate release notes, reference the appropriate `generate.yml` entrypoint CI template provided by this project from your CI file. The **generate** step can also be customized through provided [parameters](docs/samples/ci/azure-pipelines/custom/azure-pipelines.generate.yml#L4-#L7). Generation of release notes is presently *limited* to the module's [valid tags pattern](#valid-tags). -#### Releases +##### Creating releases **Note:** Ensure your main project's CI file(s) and/or settings are configured to run CI jobs for tag refs. @@ -108,6 +110,68 @@ To create releases, reference the appropriate `release.yml` entrypoint CI templa Releases supports all tag refs. Tags *need not* follow [Semantic Versioning](https://semver.org/) though the convention is recommended. +#### via Entrypoint scripts + +##### Parameters + +```powershell +# Entrypoint scripts +Invoke-Generate.ps1 [[-ProjectDirectory] ] [-ReleaseTagRef] [[-ReleaseNotesVariant] ] [[-ReleaseNotesPath] ] [] +Invoke-Release.ps1 -Namespace -Repository -ApiKey [-TagName ] [-Name ] [-ReleaseNotesPath ] [-Draft ] [-Prerelease ] [-Asset ] [] +Invoke-Release.ps1 -Namespace -Repository -ApiKey [-TagName ] [-Name ] [-ReleaseNotesContent ] [-Draft ] [-Prerelease ] [-Asset ] [] + +# Cmdlets +Generate-ReleaseNotes [-Path] [-TagName] [-Variant] {Changes-HashSubject-Merges | Changes-HashSubject-NoMerges | Changes-HashSubject | VersionDate-HashSubject-Merges | VersionDate-HashSubject-NoMerges | VersionDate-HashSubject | VersionDate-Subject-Merges | VersionDate-Subject-NoMerges | VersionDate-Subject} [-ReleaseNotesPath] [] +Create-GitHubRelease -Namespace -Repository -ApiKey [-TagName ] [-TargetCommitish ] [-Name ] [-ReleaseNotesPath ] [-Draft ] [-Prerelease ] [] +Create-GitHubRelease -Namespace -Repository -ApiKey [-TagName ] [-TargetCommitish ] [-Name ] [-ReleaseNotesContent ] [-Draft ] [-Prerelease ] [] +Upload-GitHubReleaseAsset [-UploadUrl] [-Asset] [-ApiKey] [] +``` + +##### Commands + +Simply define necessary environment variables and/or parameter values prior to executing the provided entrypoint scripts within your CI environment to perform their respective functions. + +```powershell +# CI global variables +$env:GITHUB_API_TOKEN='xxx' +$env:RELEASE_TAG_REF='vx.x.x' + +# Common variables +#$env:RELEASE_NOTES_PATH = "$(git rev-parse --show-toplevel)/.release-notes.md" # optional + +# Generate (Generates release notes) +#$env:RELEASE_NOTES_VARIANT='Changes-HashSubject-NoMerges' # optional +$private:generateArgs = @{ + #ProjectDirectory = "$(git rev-parse --show-toplevel)" # optional + ReleaseTagRef = $env:RELEASE_TAG_REF +} +if ($env:RELEASE_NOTES_VARIANT) { $private:generateArgs['ReleaseNotesVariant'] = $env:RELEASE_NOTES_VARIANT } +if ($env:RELEASE_NOTES_PATH) { $private:generateArgs['ReleaseNotesPath'] = $env:RELEASE_NOTES_PATH } +./path/to/PSRepositoryReleaseManager/src/scripts/ci/Invoke-Generate.ps1 @private:generateArgs + +# Release (Creates GitHub release) +$env:RELEASE_NAMESPACE = 'mygithubnamespace' # required +$env:RELEASE_REPOSITORY = 'my-project' # required +#$env:RELEASE_NAME = 'My release name' # optional +#$env:RELEASE_NOTES_CONTENT = Get-Content $env:RELEASE_NOTES_PATH -Raw # optional +#$env:RELEASE_DRAFT = 'false' # optional +#$env:RELEASE_PRERELEASE = 'false' # optional +#$env:RELEASE_ASSETS = @('path/to/asset1.tar.gz', 'path/to/asset2.gz', 'path/to/asset3.zip', 'path/to/asset*.gz', 'path/to/asset*.zip') # optional +$private:releaseArgs = @{ + Namespace = $env:RELEASE_NAMESPACE + Repository = $env:RELEASE_REPOSITORY + ApiKey = $env:GITHUB_API_TOKEN +} +if ($env:RELEASE_TAG_REF) { $private:releaseArgs['TagName'] = $env:RELEASE_TAG_REF } +if ($env:RELEASE_NAME) { $private:releaseArgs['Name'] = $env:RELEASE_NAME } +if ($env:RELEASE_NOTES_PATH) { $private:releaseArgs['ReleaseNotesPath'] = $env:RELEASE_NOTES_PATH } +elseif ($env:RELEASE_NOTES_CONTENT) { $private:releaseArgs['ReleaseNotesContent'] = $env:RELEASE_NOTES_CONTENT } +if ($env:RELEASE_DRAFT) { $private:releaseArgs['Draft'] = [System.Convert]::ToBoolean($env:RELEASE_DRAFT) } +if ($env:RELEASE_PRERELEASE) { $private:releaseArgs['Prerelease'] = [System.Convert]::ToBoolean($env:RELEASE_PRERELEASE) } +if ($env:RELEASE_ASSETS) { $private:releaseArgs['Asset'] = $env:RELEASE_ASSETS } +./path/to/PSRepositoryReleaseManager/src/scripts/ci/Invoke-Release.ps1 @private:releaseArgs +``` + ### Managing the submodule #### Retrieving updates