Skip to content

Commit

Permalink
Docs (readme): Improve documentation on the project
Browse files Browse the repository at this point in the history
  • Loading branch information
@joeltimothyoh
joeltimothyoh committed May 22, 2024
1 parent 3f5f160 commit 7cc5a2b
Showing 1 changed file with 41 additions and 33 deletions.
74 changes: 41 additions & 33 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down Expand Up @@ -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

Expand All @@ -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 `<VariantName>.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 `<VariantName>.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
Expand All @@ -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
Expand All @@ -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) /<br>`.release-notes.md` (relative) | false | string |
| `RELEASE_NOTES_PATH` | `.release-notes.md` (relative) /<br>`/path/to/.release-notes.md` (full) | false | string |

###### Release

Expand All @@ -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 )
Expand All @@ -173,6 +163,24 @@ 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.

#### 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
Expand Down Expand Up @@ -203,4 +211,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.

0 comments on commit 7cc5a2b

Please sign in to comment.