Skip to content

Commit

Permalink
Docs (setup): Add documentation on using the project as an independen…
Browse files Browse the repository at this point in the history
…t project
  • Loading branch information
joeltimothyoh committed May 16, 2024
1 parent 1ebe7eb commit 9826bb1
Showing 1 changed file with 21 additions and 10 deletions.
31 changes: 21 additions & 10 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,22 +9,31 @@ A project for managing repository releases, such as [GitHub releases](https://do

This project provides CI templates, scripts, and cmdlets that other projects can utilize for generating release notes and creating releases.

### Main project structure
## Setup

`PSRepositoryReleaseManager` requires main projects to adopt the following directory structure:
`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).

```shell
/build/ # Directory containing build files
/build/PSRepositoryReleaseManager/ # The root directory of PSRepositoryReleaseManager as a submodule
# Clone the repository with its submodules
git clone https://github.com/theohbrothers/PSRepositoryReleaseManager.git --recurse-submodules
```

## Configuration
### Submodule

#### Main project structure

### Main project
To use `PSRepositoryReleaseManager` as a submodule, main projects are to adopt the following directory structure:

Configure the following components on your main project.
```shell
/build/ # Directory containing build files
/build/PSRepositoryReleaseManager/ # The root directory of PSRepositoryReleaseManager as a submodule
```

#### Submodule
#### Adding the submodule

Add `PSRepositoryReleaseManager` as a submodule under the directory `build` in your main project:

Expand All @@ -50,7 +59,7 @@ Sample CI files can be found [here](docs/samples/ci).

### CI settings

Configure the following CI settings for your project.
Configure the following CI settings for your main project if `PSRepositoryReleaseManager` is to be used in a CI environment.

#### Secrets

Expand Down Expand Up @@ -129,7 +138,7 @@ Upload-GitHubReleaseAsset [-UploadUrl] <string> [-Asset] <string[]> [-ApiKey] <s

##### 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.
Simply define necessary environment variables and/or parameter values prior to executing the provided entrypoint script(s) within your CI environment to perform their respective functions.

```powershell
# CI global variables
Expand Down Expand Up @@ -172,6 +181,8 @@ if ($env:RELEASE_ASSETS) { $private:releaseArgs['Asset'] = $env:RELEASE_ASSETS }
./path/to/PSRepositoryReleaseManager/src/scripts/ci/Invoke-Release.ps1 @private:releaseArgs
```

## Maintenance

### Managing the submodule

#### Retrieving updates
Expand Down

0 comments on commit 9826bb1

Please sign in to comment.