autorel 2.5.2 → 2.5.4

package/README.md

@@ -41,19 +41,20 @@ Use Autorel to save time, prevent broken releases, and ship with confidence.
 ## Table of Contents
 
 - [Example Usage (CLI)](#example-usage-cli)
-- [Example Usage (Library)](#example-usage-library)
-- [System Requirements](#system-requirements)
-- [Commit Messages](#commit-messages)
+- [Example Usage (Library)](docs/usage-library.md)
+- [Configuring GitHub Permissions](#configuring-github-permissions)
 - [Usage with GitHub Actions](#usage-with-github-actions)
+- [Commit Messages](#commit-messages)
 - [Usage with Other Repositories (not GitHub)](#usage-with-other-repositories-not-github)
 - [Usage with Other Languages (not Node.js)](#usage-with-other-languages-not-nodejs)
-- [Configuration](#configuration)
-- [Sample YAML Configuration](#sample-yaml-configuration)
+- [Configuration](docs/configuration.md)
+- [Sample YAML Configuration](docs/configuration.md#sample-yaml-configuration)
 - [Types](#types)
-- [Debug Mode](#debug-mode)
+- [Verbose Mode](#verbose-mode)
 - [About package.json versions](#about-packagejson-versions)
 - [FAQ](docs/faq.md)
-- [Support, Feedback, and Contributions](#support-feedback-and-contributions)
+- [System Requirements](#system-requirements)
+- [Contributing](#contributing)
 - [License](#license)
 
 ## Example Usage (CLI)
@@ -76,40 +77,23 @@ npm i -g autorel
 autorel --publish
 ```
 
-### ⚠️ Avoiding Breaking Changes
-
-If using the `npx` command, you may want to append the version number to prevent breaking changes in the future. You can do this by appending `@^` followed by the major version number, ie. `npx autorel@^2`.
+> ⚠️ If using the `npx` command, you may want to append the version number to prevent breaking changes in the future. You can do this by appending `@^` followed by the major version number, ie. `npx autorel@^2`.
 
 ## Example Usage (Library)
 
-1. Install `autorel` as a dependency
+See [Using `autorel` as a library](/docs/usage-library.md)
 
-    ```bash
-    npm i autorel
-    ```
+## Configuring GitHub Permissions
 
-2. Import and use in your project to build custom release tooling
+In order for `autorel` to create releases and publish to GitHub's npm registry, you'll need to make sure you have the appropriate access/permissions.
 
-    ```typescript
-    import {autorel, defaultConfig} from 'autorel';
+If you're using GitHub Actions, see [Using `autorel` with GitHub Actions](/docs/github-actions.md#permissions) for more information.
 
-    const autorelConfig = {
-      ...defaultConfig,
-      publish: true,
-    };
+If you're running it locally (or using a different CI/CD system), you can pass your [GitHub Personal Access Token (PAT)](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) either by setting the `GITHUB_TOKEN` environment variable or by passing the `--github-token (githubToken: string)` flag.
 
-    autorel(autorelConfig).then((nextVersion) => {
-        console.log(`Next version is ${nextVersion}`); // ie, "Next version is 1.0.1"
-    });
-    ```
+## Usage with GitHub Actions
 
-## System Requirements
-
-- Linux or MacOS (Windows is not officially supported)
-- Node.js 14+
-- NPM 7+
-- Git 2.13+
-- Bash
+Autorel 💜 GitHub Actions. See [Using `autorel` with GitHub Actions](/docs/github-actions.md)
 
 ## Commit Messages
 
@@ -123,265 +107,51 @@ Here are some examples of commit messages and the resulting [SemVer](https://sem
 
 You can find more examples in the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) documentation.
 
-## Usage with GitHub Actions
-
-You can use `autorel` with GitHub Actions to automate your releases (recommended). 
-
-> ❗️ You must set `fetch-depth: 0` and `fetch-tags: true` in `actions/checkout@v4` (or later) or autorel will not work correctly.
-
-> ❗️ You must be authenticated with NPM to publish. To do so via GitHub Actions, see [this](https://docs.github.com/en/actions/guides/publishing-nodejs-packages#publishing-packages-to-the-npm-registry).
-
-Here is a sample configuration:
-
-```yaml
-name: Release
-on:
-  push:
-    branches: [main, alpha, beta]
-jobs:
-  release:
-    name: Release
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-          fetch-tags: true
-      - uses: actions/setup-node@v4
-        with:
-          node-version: latest
-          registry-url: "https://registry.npmjs.org"
-          cache: 'npm'
-      - run: npx autorel@^2
-        env:
-            GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}
-            NODE_AUTH_TOKEN: ${{secrets.NPM_TOKEN}}
-```
-
-It's also recommended you create a `.autorel.yaml` file in the root of your project to [configure](#configuration) `autorel`.
-
-## Usage with Other Repositories (not GitHub)
-
-`autorel` is designed to work with any CI/CD system, not just GitHub Actions. You can use it with GitLab, Bitbucket, Jenkins, or any other system that supports running shell commands.
-
-Simply use the `--skip-release` flag (arg: `skipRelease: true`) to skip creating a release on GitHub. Then, you can use the `--run` flag (arg: `run: string`) to run any command or script after the version bump with the new version number available as an environment variable [see below](#run).
-
-If you're interested in contributing built-in support for other systems, please open an issue or PR.
-
-## Usage with Other Languages (not Node.js)
-
-`autorel` is designed to work with any language or platform. You can use it with Python, Ruby, Go, Java, or any other language.
-
-Simply omit the `--publish` flag (arg: `publish: false`, which is default) to skip publishing to NPM. Then, you can use either the `--run` flag (arg: `run: string`) or `runScript: string` arg to run any command or script after the version bump with the new version number available as an environment variable [see below](#run).
-
-If you're interested in contributing built-in support for other systems, please open an issue or PR.
-
 ## Configuration
 
-When run in CLI mode, `autorel` can be configured via CLI arguments or a `yaml` file. CLI arguments take precedence over the `yaml` file. All parameters are optional.
-
-However, omitting optional binary flags, such as the `--publish`, `--dry-run`, `--skip-release`, and `--verbose` flags will still publish to NPM if set in the `yaml` file.
-
-When used as a library, you pass the configuration directly to the `autorel` function. When used this way, it will not automatically load any default configuration—you can use the `defaultConfig` object to get the default configuration:
-
-```typescript
-import {autorel, defaultConfig} from 'autorel';
-
-const autorelConfig = {
-  ...defaultConfig,
-  publish: true,
-};
-```
-
-> ❗️ The `yaml` configuration file must be named `.autorel.yaml` and be in the root of your project.
-
-[See sample YAML configuration](#sample-yaml-configuration)
-
-### publish
-
-Whether to publish the release to NPM. If `true`, you must be authenticated with NPM. To do so via GitHub Actions, see [this](https://docs.github.com/en/actions/guides/publishing-nodejs-packages#publishing-packages-to-the-npm-registry).
-
-- CLI: `--publish`
-- Argument: `publish: boolean`
-- Default: `false`
-
-### dryRun
-
-Whether to run in dry-run mode. This will not push the tag, create the release, publish to NPM, or run the command.
+See [Configuration](docs/configuration.md) for reference and examples.
 
-- CLI: `--dry-run`
-- Argument: `dryRun: boolean`
-- Default: `false`
-
-### verbose
-
-Whether to run in verbose mode. This will output more information about the release process.
-
-- CLI: `--verbose`
-- Argument: `verbose: boolean`
-- Default: `false`
-
-### skipRelease
-
-Whether to skip creating a release on GitHub. If `true`, the release will not be created, but the tag will still be pushed and the package on npm will still be updated, if applicable.
-
-- CLI: `--skip-release`
-- Argument: `skipRelease: boolean`
-- Default: `false`
-
-### run
-
-A `bash` command/script to run after the release is complete. All scripts are run in "-e" mode, meaning they will exit on the first error.
+## Types
 
-The following environment variables are available:
+You can find the types defined at [src/index.ts](src/index.ts).
 
-| Variable | Description |
-| --- | --- |
-| `NEXT_VERSION` | The new version number (without the `v`) |
-| `NEXT_TAG` | The new tag, ie. v3.1.0 |
+## Verbose Mode
 
-Example CLI usage:
+To enable verbose mode, set `--verbose (verbose: true)` or environment variable `AUTOREL_DEBUG=1`:
 
 ```bash
-npx autorel --run 'echo "Next version is ${NEXT_VERSION}"'
+npx autorel --verbose
 ```
 
-Example YAML usage:
-
-```yaml
-run: echo "Next version is ${NEXT_VERSION}"
-```
-
-You can use the multi-line string syntax in YAML to write a script:
-
-```yaml
-run: |
-  echo "$(date +"%Y-%m-%d") ${NEXT_VERSION}" >> versions.txt
-  aws s3 sync . s3://my-bucket
-```
-
-- CLI: `--run`
-- Argument: `run: string`
-- Default: `undefined`
-
-### preRun
-
-A `bash` command/script to run before the release is started. All scripts are run in "-e" mode, meaning they will exit on the first error. Here's where you can do things like run tests or do build steps.
-
-This could save you time and money by not running unnecessary steps in your CI/CD pipeline. It will not run if no release is determined to be necessary, and it will not run in dry-run mode.
-
-This is run *after* determining the new version number but *before* pushing tags, creating the release on GitHub, updating the package.json, or publishing to NPM. 
-
-Example YAML usage: 
-
-```yaml
-preRun: |
-  npm ci
-  npm run build
-  npm run test
-  npm run lint
-```
-
-- CLI: `--pre-run`
-- Argument: `preRun: string`
-- Default: `undefined`
-
-### preRelease
-
-> ❗️ This is typically set via the `branches` configuration (recommended), but can be overridden here.
-
-The pre-release channel to use. This will be appended to the version number. For example, if the version is `1.0.0` and the pre-release is `alpha`, the version will be `1.0.0-alpha.1`. For "production" releases, the "latest" tag will be used for NPM.
-
-- CLI: `--pre-release`
-- Argument: `preRelease: string`
-- Default: `undefined`
-
-### breakingChangeTitle (YAML/library only)
-
-The title to use for the breaking changes section in the release notes.
-
-- Argument: `breakingChangeTitle: string`
-- Default: `"🚨 Breaking Changes 🚨"`
-
-### commitTypes (YAML/library only)
-
-The commit types to use for both the release notes and version bumping.
-
-- Argument: `commitTypes: CommitType[]`
-- Defaults: [src/defaults.ts](src/defaults.ts)
-
-### branches (YAML/library only)
-
-The branches to use for the release along with their pre-release channel. If not provided, the default is:
-
-```yaml
-- {name: 'main'}
-```
-
-The above will release to the `latest` channel on NPM. If you want to release to a different channel (making it a pre-release), you can specify it like so:
-
-```yaml
-branches:
-  - {name: 'main'}
-  - {name: 'develop', prereleaseChannel: 'alpha'}
-  - {name: 'staging', prereleaseChannel: 'beta'}
-```
-
-The above will release to the `latest` channel (production) on NPM for the `main` branch, the `alpha` pre-release channel for the `develop` branch, and the `beta` pre-release channel for the `staging` branch.
-
-- Argument: `branches: ReleaseBranch[]`
-
-### useVersion
-
-The version to use for the release INSTEAD of the version being generated. Always results in a release being created unless `noRelease` is `true`. **Advanced usage only, not recommended for most users.**
-
-- CLI: `--use-version`
-- Argument: `useVersion: string`
-- Default: `undefined`
-
-> ❗️ Must be a valid SemVer version, without the `v`.
-
-### githubToken
-
-The GitHub token to use for creating the release. If not provided, it will use the `GITHUB_TOKEN` environment variable. This is only used if `skipRelease` is `false`.
-
-## Sample YAML Configuration
+## About package.json versions
 
-<sub>_.autorel.yaml_</sub>
-```yaml
-# Define the branches and their respective channels
-branches:
-  - {name: 'main'}
-  - {name: 'next', prereleaseChannel: 'next'}
+If using our npm publishing feature, the package.json file's version will be updated in memory before being pushed to npm, as this is the only place where it's actually required. The change will not be pushed to the repository, as it is not necessary and could cause conflicts. See [this post](https://semantic-release.gitbook.io/semantic-release/support/faq)
 
-# Enable publishing to NPM
-publish: true
+If you need access to the new version number in your CI/CD pipeline, you can use the `NEXT_VERSION` or `NEXT_TAG` environment variables.
 
-# Run custom script after publish
-run: |
-  echo "$(date +"%Y-%m-%d") ${NEXT_VERSION}" >> versions.txt
-  aws s3 sync . s3://my-bucket
-```
+## Usage with Other Repositories (not GitHub)
 
-## Types
+`autorel` is designed to work with any CI/CD system, not just GitHub Actions. You can use it with GitLab, Bitbucket, Jenkins, or any other system that supports running shell commands.
 
-You can find the types defined at [src/index.ts](src/index.ts).
+Simply use the `--skip-release` flag (arg: `skipRelease: true`) to skip creating a release on GitHub. Then, you can use the `--run` flag (arg: `run: string`) to run any command or script after the version bump with the new version number available as an environment variable [see below](#run).
 
-## Debug Mode
+If you're interested in contributing built-in support for other systems, please open an issue or PR.
 
-To enable debug mode, set `AUTOREL_DEBUG=1`:
+## Usage with Other Languages (not Node.js)
 
-```bash
-AUTOREL_DEBUG=1 npx autorel
-```
+`autorel` is designed to work with any language or platform. You can use it with Python, Ruby, Go, Java, or any other language.
 
-This will output configuration and other debug information.
+Simply omit the `--publish` flag (arg: `publish: false`, which is default) to skip publishing to NPM. Then, you can use either the `--run` flag (arg: `run: string`) or `runScript: string` arg to run any command or script after the version bump with the new version number available as an environment variable [see below](#run).
 
-## About package.json versions
+If you're interested in contributing built-in support for other systems, please open an issue or PR.
 
-If using our npm publishing feature, the package.json file's version will be updated in memory before being pushed to npm, as this is the only place where it's actually required. The change will not be pushed to the repository, as it is not necessary and could cause conflicts. See [this post](https://semantic-release.gitbook.io/semantic-release/support/faq)
+## System Requirements
 
-If you need access to the new version number in your CI/CD pipeline, you can use the `NEXT_VERSION` or `NEXT_TAG` environment variables.
+- Linux or MacOS (Windows is not officially supported)
+- Node.js 14+
+- npm 7+
+- Git 2.13+
+- Bash
 
 ## Contributing
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "autorel",
-  "version": "2.5.2",
+  "version": "2.5.4",
   "description": "Automate semantic releases based on conventional commits. Similar to semantic-release but much simpler.",
   "license": "MIT",
   "author": "Marc H. Weiner <mhweiner234@gmail.com> (https://mhweiner.com)",