From 3d5a6da49cdc4a65bbddc121fdcbad39740f9ab9 Mon Sep 17 00:00:00 2001 From: Aviv Ben Shahar Date: Tue, 4 Jun 2024 03:29:36 +0300 Subject: [PATCH] =?UTF-8?q?docs:=20full=20docs=20about=20CI=20/=20CD,=20`s?= =?UTF-8?q?emantic-release`,=20versioning=20and=20runtime=20-=20client=20W?= =?UTF-8?q?IP=20=F0=9F=A5=B7?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/.vitepress/sidebar.config.mts | 24 +++ docs/app/ci/github-actions.md | 184 ++++++++++++++++++ docs/app/ci/semantic-release.md | 85 ++++++++ docs/app/client/client.md | 8 + docs/app/quick-start.md | 29 ++- docs/app/setup/bundler-options.md | 8 +- docs/app/setup/runtime-explain.md | 25 +++ docs/app/setup/versioning.md | 18 +- docs/app/troubleshooting/empty-glob.md | 4 +- .../troubleshooting/missing-config-file.md | 6 +- docs/index.md | 10 +- 11 files changed, 382 insertions(+), 19 deletions(-) create mode 100644 docs/app/ci/github-actions.md create mode 100644 docs/app/ci/semantic-release.md create mode 100644 docs/app/client/client.md create mode 100644 docs/app/setup/runtime-explain.md diff --git a/docs/.vitepress/sidebar.config.mts b/docs/.vitepress/sidebar.config.mts index f689fb1..88fd4ae 100755 --- a/docs/.vitepress/sidebar.config.mts +++ b/docs/.vitepress/sidebar.config.mts @@ -7,6 +7,10 @@ export const SIDEBAR: DefaultTheme.Sidebar = [ link: '../quick-start', collapsed: false, items: [ + { + text: 'Node.js Runtime ๐Ÿš€', + link: 'runtime-explain', + }, { text: 'Bundler Options ๐Ÿ—๏ธ', link: 'bundler-options', @@ -21,6 +25,26 @@ export const SIDEBAR: DefaultTheme.Sidebar = [ }, ], }, + { + text: 'CI / CD ๐Ÿ™', + base: '/app/ci/', + collapsed: false, + items: [ + { + text: 'GitHub Actions ๐Ÿค–', + link: 'github-actions', + }, + { + text: 'Semantic Release ๐Ÿš€', + link: 'semantic-release', + }, + ], + }, + { + text: 'Client', + base: '/app/client/', + link: 'client', + }, { text: 'Troubleshooting', base: '/app/troubleshooting/', diff --git a/docs/app/ci/github-actions.md b/docs/app/ci/github-actions.md new file mode 100644 index 0000000..5553249 --- /dev/null +++ b/docs/app/ci/github-actions.md @@ -0,0 +1,184 @@ +--- +prev: false +next: true +--- + +# GitHub Actions :octopus: + +### Description + +`fast-alfred` CI / CD template recommends you work with [GitHub Actions](https://docs.github.com/en/actions). + +At the end of this process, you'd be able to publish your Workflow into GitHub Releases. + +::: warning Note :warning: +The following example uses `semantic-release` mechanism and all related packages. +Please follow the [Semantic Release](./semantic-release) guide to set up your project. + +::: + +## Setup + +::: tip Note :zap: +Copy these files into your `.github/workflows` folder, at the root of your project. +You can modify them to fit your needs. The current structure is a suggestion to reduce the maintenance of your CI / CD. +::: + +::: code-group + +```yaml [.github/workflows/release-master.yaml] +--- +name: '๐Ÿ“ฆ Create New Release' + +on: + push: + branches: + - master + +permissions: + contents: write + pull-requests: write + issues: write + deployments: write + +concurrency: + group: release-master-${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true + +jobs: + checks: + name: โœ… Check for Release + runs-on: ubuntu-latest + timeout-minutes: 15 + + env: + HUSKY: 0 + + steps: + - name: Checkout + uses: actions/checkout@v4 + with: + fetch-depth: 1 + + - name: ๐Ÿงช Check out repository code + uses: ./.github/workflows/health-check + with: + run-tests: 'false' + + release: + name: ๐Ÿ“ฆ Release Version + runs-on: ubuntu-latest + timeout-minutes: 60 + needs: + - checks + + env: + HUSKY: 0 + + steps: + - name: Checkout + uses: actions/checkout@v4 + with: + fetch-depth: 0 + persist-credentials: false + + - name: Git Config + run: | + git config --global user.name "github-bot" + git config --global user.email "github-bot@gmail.com" + + - name: ๐Ÿ–ฅ๏ธ Setup Env + uses: ./.github/workflows/install + + - name: Release + env: + GITHUB_TOKEN: ${{ secrets.GH_TOKEN }} + GIT_AUTHOR_NAME: github-bot + GIT_AUTHOR_EMAIL: github-bot@gmail.com + GIT_COMMITTER_NAME: github-bot + GIT_COMMITTER_EMAIL: github-bot@gmail.com + run: | + npx semantic-release +``` + +```yaml [.github/workflows/health-check/action.yaml] +--- +name: 'โ˜‘๏ธ Checks Pipeline' +description: 'Checks the codebase health' + +inputs: + run-tests-command: + description: 'Run tests command, default is `npm test`' + default: 'npm test' + required: false + + run-tests: + description: 'Run tests' + default: 'true' + required: false + + run-lint-command: + description: 'Run linter command, default is `npm run lint`' + default: 'npm run lint' + required: false + + run-lint: + description: 'Run lint' + default: 'true' + required: false + + run-build-command: + description: 'Run build command, default is `npm run build`' + default: 'npm run build' + required: false + + run-build: + description: 'Run build' + default: 'true' + required: false + +runs: + using: composite + steps: + - name: ๐Ÿ–ฅ๏ธ Setup Env + uses: ./.github/workflows/install + + - name: ๐Ÿงช Test + if: ${{ inputs.run-tests == 'true' }} + shell: bash + run: | + ${{ inputs.run-tests-command }} + + - name: ๐Ÿ”จ Build + if: ${{ inputs.run-build == 'true' }} + shell: bash + run: | + ${{ inputs.run-build-command }} + + - name: โœ… Lint + if: ${{ inputs.run-lint == 'true' }} + shell: bash + run: | + ${{ inputs.run-lint-command }} +``` + +```yaml [.github/workflows/install/action.yaml] +--- +name: 'โ˜‘๏ธ Install deps' +description: 'Install dependencies and setup node' + +runs: + using: composite + steps: + - name: ๐Ÿ–ฅ๏ธ Setup Node + uses: actions/setup-node@v4 + with: + node-version: 20 + + - name: ๐Ÿ”— Install Dependencies + shell: bash + run: | + npm ci --no-fund --no-audit --no-progress --ignore-scripts +``` + +::: diff --git a/docs/app/ci/semantic-release.md b/docs/app/ci/semantic-release.md new file mode 100644 index 0000000..633957b --- /dev/null +++ b/docs/app/ci/semantic-release.md @@ -0,0 +1,85 @@ +--- +prev: true +next: false +--- + +# Semantic Release :rocket: + +### Description + +`fast-alfred` CI / CD template recommends you work with [`semantic-release`](https://github.com/semantic-release/semantic-release). + +## Installation + +```bash +npm install semantic-release @semantic-release/{changelog,commit-analyzer,exec,git,github,release-notes-generator} +``` + +## Setup + +::: warning Note :warning: +Fill in the upper case placeholders with your own values, such as `REPO_NAME`, `WORKFLOW_NAME`, etc. +::: + +Create a `.releaserc` file in the root of your project and add the following configuration: + +::: code-group + +```json [.releaserc] +{ + "$schema": "https://json.schemastore.org/semantic-release.json", + "repositoryUrl": "https://github.com/REPO_NAME.git", + "branches": [ + "+([0-9])?(.{+([0-9]),x}).x", + "master", + "next", + "next-major", + { + "name": "beta", + "prerelease": true + }, + { + "name": "alpha", + "prerelease": true + } + ], + "tagFormat": "v${version}", + "plugins": [ + "@semantic-release/commit-analyzer", + "@semantic-release/release-notes-generator", + [ + "@semantic-release/changelog", + { + "changelogFile": "CHANGELOG.md" + } + ], + [ + "@semantic-release/exec", + { + "prepareCmd": "npx fast-alfred -t ${nextRelease.version}" + } + ], + [ + "@semantic-release/git", + { + "assets": ["package.json", "package-lock.json", "info.plist", "CHANGELOG.md"], + "message": "chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}" + } + ], + [ + "@semantic-release/github", + { + "assets": [ + { + "path": "./esbuild/WORKFLOW_NAME.alfredworkflow", + "label": "WORKFLOW_NAME.alfredworkflow", + "name": "WORKFLOW_NAME.alfredworkflow" + } + ] + } + ] + ] +} +``` + +::: diff --git a/docs/app/client/client.md b/docs/app/client/client.md new file mode 100644 index 0000000..02f7bf2 --- /dev/null +++ b/docs/app/client/client.md @@ -0,0 +1,8 @@ +--- +prev: false +next: false +--- + +# `fast-alfred` Client + + diff --git a/docs/app/quick-start.md b/docs/app/quick-start.md index 792373c..b2fe43b 100755 --- a/docs/app/quick-start.md +++ b/docs/app/quick-start.md @@ -1,8 +1,8 @@ --- prev: false next: - text: 'Install Command' - link: '/app/commands/install' + text: 'Node.js Runtime ๐Ÿš€' + link: '/app/setup/runtime-explain' --- # Quick Start @@ -13,7 +13,30 @@ next: npm install fast-alfred ``` -## The Reason +### Configuration + +Create a `.fast-alfred.config.cjs` file in the root of your project and add the following configuration: + +```javascript +/** + * @type {import('fast-alfred').FastAlfredConfig} + */ +module.exports = {} +``` + +### Build Your First Workflow + +1. Create a Workflow via Alfred UI, or use an existing one +1. Open the Workflow directory, copy relevant files +1. Create a new directory for your Workflow + +1. Use `fast-alfred` client utilities to manage your Workflow +1. Call your scripts using [`fast-alfred` runtime](./setup/runtime-explain) + +
+
+ +# The Reason `fast-alfred` lets you think about the functionality, rather than the boilerplate. diff --git a/docs/app/setup/bundler-options.md b/docs/app/setup/bundler-options.md index 09c2eca..2a7b41c 100644 --- a/docs/app/setup/bundler-options.md +++ b/docs/app/setup/bundler-options.md @@ -14,7 +14,7 @@ named `.fast-alfred.config.cjs`. # Available Options -::: tip Note :bulb: +::: tip Note :zap: `fast-alfred` has a default configuration that should work for most of the workflows. ::: @@ -80,12 +80,10 @@ module.exports = { By default, `fast-alfred` would place all the output files under the `esbuild` directory. You can change that by setting the `targetDir` property. - - ::: warning CI / CD Usage :rotating_light: -If you're using the `fast-alfred` CI / CD template, updating the `targetDir` property should be handled automatically. -Make sure `pack` script works correctly. +If you're using the [`fast-alfred` CI / CD template](/app/ci/github-actions), updating the `targetDir` property should be handled automatically. +Make sure `npx fast-alfred pack` script works correctly. ::: ##### Example diff --git a/docs/app/setup/runtime-explain.md b/docs/app/setup/runtime-explain.md new file mode 100644 index 0000000..17feac4 --- /dev/null +++ b/docs/app/setup/runtime-explain.md @@ -0,0 +1,25 @@ +--- +prev: true +next: true +--- + +# Runtime Explain :rocket: + +`fast-alfred` provides an out-of-the-box shell script to call the bundled files in the workflow. + +The main advantage of this approach is that your Node.js script would be executed in an environment that is aware of the Alfred workflow, and it will be able to interact with it, as well as having caching and other features. + +## How It Works + +At build time, an additional asset, named `run-node.sh` would be attached to the workflow, under the `assets` directory. +This script is responsible for executing the bundled Node.js script. + +### Example + +::: tip TIP :zap: +The code below is an example of how to trigger your Node.js script in an Alfred Script Filter. +::: + +```bash +./esbuild/assets/run-node.sh esbuild/bookmarks.js "$1" +``` diff --git a/docs/app/setup/versioning.md b/docs/app/setup/versioning.md index 12ce16d..29f5cc4 100644 --- a/docs/app/setup/versioning.md +++ b/docs/app/setup/versioning.md @@ -7,12 +7,24 @@ next: false `fast-alfred` provides a way to manage your workflow version automatically. -In order to sync the version across `package.json` and `info.plist`, just pass in to `fast-alfred` the version you want to use: +In order to sync the version across `package.json` and `info.plist`, just pass in to +`fast-alfred` the version you want to use: ```bash -npx fast-alfred 1.2.3 # This will set the version to 1.2.3 +npx fast-alfred -t 1.2.3 # This will set the version to 1.2.3 ``` -## Versioning in `package.json` :arrows_counterclockwise: +## Versioning By Commits Using `semantic-release` :arrows_counterclockwise: `fast-alfred` CI / CD template recommend you to work with [`semantic-release`](https://github.com/semantic-release/semantic-release) in order to track and manage your workflow version :rocket: +You can find more details in the [Semantic Release](../ci/semantic-release.md) section. + +### See the [CI / CD section](/app/ci/github-actions) for more details :sparkles: + +## Options + +- `-t` or `--target-version`: Set the version to use +- `--no-pack`: Skip the packing process + +- `-h` or `--help`: Display help message +- `--verbose`: Display verbose output diff --git a/docs/app/troubleshooting/empty-glob.md b/docs/app/troubleshooting/empty-glob.md index b42da49..2d43ba0 100644 --- a/docs/app/troubleshooting/empty-glob.md +++ b/docs/app/troubleshooting/empty-glob.md @@ -18,9 +18,7 @@ Note that the default glob pattern refers to TypeScript files, but you can chang ## Solution - - -::: tip TIP โšก๏ธ +::: tip TIP :zap: You can find the default configuration options in the [API Reference](/app/setup/bundler-options#productionscripts). ::: diff --git a/docs/app/troubleshooting/missing-config-file.md b/docs/app/troubleshooting/missing-config-file.md index 16db529..fbacc5d 100755 --- a/docs/app/troubleshooting/missing-config-file.md +++ b/docs/app/troubleshooting/missing-config-file.md @@ -15,10 +15,8 @@ Taking default values! ## Solution - - -::: tip TIP โšก๏ธ -You can find the default configuration options in the [API Reference](/api/fast-alfred/fast-alfred-config). +::: tip TIP :zap: +You can find the default configuration options in both [Bundler Options](/app/setup/bundler-options) and [Workflow Metadata](/app/setup/workflow-metadata). ::: Simply add a `.fast-alfred.config.cjs` file at the root of your project. diff --git a/docs/index.md b/docs/index.md index 4aac7ef..df6f13f 100755 --- a/docs/index.md +++ b/docs/index.md @@ -17,9 +17,17 @@ hero: link: /app/troubleshooting/index features: - title: Node.js Runtime - link: '/app/setup/bundler-options' + link: '/app/setup/runtime-explain' details: A convenient shell file to run your Alfred workflow with Node.js. icon: '๐Ÿš€' + - title: Powerful Client + link: '/app/client/client' + details: A powerful client to manage and optimize your Alfred workflow. + icon: '๐Ÿ•น๏ธ' + - title: GitHub Actions + link: '/app/ci/github-actions' + details: A CI/CD template to automate your workflow deployment. + icon: '๐Ÿ™' - title: Bundle Management link: '/app/setup/bundler-options' details: Automatically bundle your workflow into a `.alfredworkflow` file.