diff --git a/README.md b/README.md index aa1e27a..7a847ab 100644 --- a/README.md +++ b/README.md @@ -7,23 +7,25 @@ A project for managing repository releases, such as [GitHub releases](https://do ## Introduction -This project provides CI templates, scripts, and cmdlets that other projects can utilize for generating release notes and creating releases. +This project provides entrypoint scripts, CI templates, and PowerShell cmdlets that other projects can utilize for generating release notes and creating releases. ## Setup -`PSRepositoryReleaseManager` can be used as an [independent project](#independent-project), or as [a submodule](#submodule) for generating release notes and creating releases. +`PSRepositoryReleaseManager` can be used as an [independent project](#independent-project), or as a [submodule](#submodule) for generating release notes and creating releases. ### Independent project -To use `PSRepositoryReleaseManager` as an independent project, simply clone a copy of the repository including its submodules to development or CI environment(s) prior to executing [generate and release steps](#usage). +To use `PSRepositoryReleaseManager` as an independent project, simply perform a clone of the repository including its submodules to development or CI environment(s) prior to executing provided [entrypoint script(s)](#usage) to perform their respective functions. ```shell -# Clone the repository with its submodules +# Clone PSRepositoryReleaseManager with its submodules git clone https://github.com/theohbrothers/PSRepositoryReleaseManager.git --recurse-submodules ``` ### Submodule +`PSRepositoryReleaseManager` can be used as submodule together with provided CI [remote template(s)](#ci-files). + #### Main project structure To use `PSRepositoryReleaseManager` as a submodule, main projects are to adopt the following directory structure: @@ -53,13 +55,13 @@ git commit -am 'Add submodule PSRepositoryReleaseManager vx.x.x' #### CI files -Decide on which CI provider to use in your main project based on those supported by this project. Setup the CI file(s) for your main project. Then simply reference the relevant CI files of this project from your main project's CI file(s). +Decide on which CI provider to use in your main project based on those supported by this project. Then setup the CI file(s) for your main project, referencing relevant CI remote template(s) of this project from your main project's CI file(s). Sample CI files can be found [here](docs/samples/ci). ### CI settings -Configure the following CI settings for your main project if `PSRepositoryReleaseManager` is to be used in a CI environment. + Configure the following CI settings for your main project if `PSRepositoryReleaseManager` is to be used in a CI environment, whether it be as an independent project or a submodule. #### Secrets @@ -69,23 +71,27 @@ Configure the following CI settings for your main project if `PSRepositoryReleas Add a secret variable `GITHUB_API_TOKEN` containing your [GitHub API token](https://docs.github.com/en/github/authenticating-to-github/keeping-your-account-and-data-secure/creating-a-personal-access-token), ensuring it has write permissions to the repository. +In the case where GitHub Actions is used for releases, the job token [`GITHUB_TOKEN`](docs/samples/ci/github/generic/github-workflows.linux.container.yml#L67) may be used for creating releases should it have write permissions to the repository. + ## Usage +The project provides a set of [entrypoint scripts](src/scripts/ci) for generating release notes and creating releases for other projects, designed to be used identically in both [development](#development) and [CI environments](#continuous-integration-ci). + ### Development #### Generating release notes -The entrypoint script [`Invoke-Generate.ps1`](src/scripts/ci/Invoke-Generate.ps1) is used to generate release notes based off local repositories. To generate one, specify the path to the local repository, the release tag ref, the release notes variant, and the release notes path. +The entrypoint script [`Invoke-Generate.ps1`](src/scripts/ci/Invoke-Generate.ps1) is used to generate release notes for any local git repository. To do so, simply define applicable [environment variables](#environment-variables) before executing the entrypoint script. The project also includes [`.vscode/tasks.json`](.vscode/tasks.json) which allows invocation of `Invoke-Generate.ps1` via [*Build Tasks*](https://code.visualstudio.com/docs/editor/tasks) in [VSCode](https://code.visualstudio.com/). Simply execute the relevant build task while entering custom or default values per variable prompt. ##### Variants -The names of all release notes variants that can be generated can be found in the module's [`generate/variants`](src/PSRepositoryReleaseManager/generate/variants) directory and goes by the convention `.ps1`. +The names of all available release notes variants that can be chosen from can be found in the module's [`generate/variants`](src/PSRepositoryReleaseManager/generate/variants) directory, and goes by the convention `.ps1`. ##### Valid tags -At present, generation of release notes is only possible for tags of the format `MAJOR.MINOR.PATCH`, prepended with a lowercase `v`: +At present, the generating of release notes is only possible for tags following the format `MAJOR.MINOR.PATCH`, prepended with a lowercase `v`: ```shell # Valid tags @@ -99,30 +105,14 @@ git tag v1.0.12-beta.1 #### 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. +The entrypoint script [`Invoke-Release.ps1`](src/scripts/ci/Invoke-Release.ps1) can be used to create releases for GitHub repositories. To do so, simply define applicable [environment variables](#environment-variables) before executing the entrypoint script. ### Continuous Integration (CI) -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. - -#### 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). - -##### Creating releases - -**Note:** Ensure your main project's CI file(s) and/or settings are configured to run CI jobs for tag refs. - -To create releases, reference the appropriate `release.yml` entrypoint CI template provided by this project from your CI file. The **release** step can also be customized through provided [parameters](docs/samples/ci/azure-pipelines/custom/azure-pipelines.release.yml#L4-#L21). - -Releases supports all tag refs. Tags *need not* follow [Semantic Versioning](https://semver.org/) though the convention is recommended. - #### via Entrypoint script(s) +The following are environment variables supported by the provided [entrypoint scripts](src/scripts/ci) for generating release notes and creating releases. + ##### Environment variables ###### Generate and Release @@ -137,7 +127,7 @@ Releases supports all tag refs. Tags *need not* follow [Semantic Versioning](htt | Name | Example value | Mandatory | Type | |:-:|:-:|:-:|:-:| | `RELEASE_NOTES_VARIANT` | `VersionDate-HashSubjectAuthor-NoMerges-Categorized` ([List of available variants](src/PSRepositoryReleaseManager/generate/variants)) | false | string | -| `RELEASE_NOTES_PATH` | `/path/to/.release-notes.md` (full) /
`.release-notes.md` (relative) | false | string | +| `RELEASE_NOTES_PATH` | `.release-notes.md` (relative) /
`/path/to/.release-notes.md` (full) | false | string | ###### Release @@ -154,11 +144,11 @@ Releases supports all tag refs. Tags *need not* follow [Semantic Versioning](htt ##### Commands -Simply populate applicable environment variables values prior to executing provided entrypoint script(s) within the CI environment to perform their respective functions. +To generate release notes and create releases, simply clone a specified *version* of the project, and define applicable [environment variables](#environment-variables) before executing the project's provided entrypoint script(s) within the CI environment. ```shell -# Clone project -git clone https://github.com/theohbrothers/PSRepositoryReleaseManager.git --recurse-submodules +# Clone PSRepositoryReleaseManager +git clone https://github.com/theohbrothers/PSRepositoryReleaseManager.git --recurse-submodules --branch 'vx.x.x' # Specify tag ref to checkout to # Process applicable environment variables export PROJECT_DIRECTORY=$( git rev-parse --show-toplevel ) @@ -173,6 +163,26 @@ pwsh -c './PSRepositoryReleaseManager/src/scripts/ci/Invoke-Generate.ps1' pwsh -c './PSRepositoryReleaseManager/src/scripts/ci/Invoke-Release.ps1' ``` +**Note:** Ensure the environment variable [`GITHUB_API_TOKEN`](#github-api-token) is defined prior to creating releases. + +Sample CI files demonstrating this approach can be found [here](docs/samples/ci/github/generic). + +#### via Submodule and CI 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). + +##### Creating releases + +**Note:** Ensure your main project's CI file(s) and/or settings are configured to run CI jobs for tag refs. + +To create releases, reference the appropriate `release.yml` entrypoint CI template provided by this project from your CI file. The **release** step can also be customized through provided [parameters](docs/samples/ci/azure-pipelines/custom/azure-pipelines.release.yml#L4-#L21). + +Releases supports all tag refs. Tags *need not* follow [Semantic Versioning](https://semver.org/) though the convention is recommended. + ## Maintenance ### Managing the submodule @@ -203,4 +213,4 @@ git commit -am 'Bump PSRepositoryReleaseManager to vx.x.x' ## Best practices - Use only tag refs of `PSRepositoryReleaseManager` in your main project. -- Ensure your main project's CI file(s) is configured to use the CI templates of `PSRepositoryReleaseManager` and that the ref used matches that of the `PSRepositoryReleaseManager` submodule used in your main project. +- For using the [submodule and CI templates](#via-submodule-and-ci-templates) approach, ensure your main project's CI file(s) is configured to use the CI templates of `PSRepositoryReleaseManager` and that the ref used matches that of the `PSRepositoryReleaseManager` submodule used in your main project.