From 086771a22bd7eb235fa9019f5d8da3843a10da81 Mon Sep 17 00:00:00 2001 From: Carlos Santiago <5726971+csantiago132@users.noreply.github.com> Date: Thu, 3 Oct 2024 14:11:18 -0500 Subject: [PATCH] feat(ci): adds github actions workflow (#21) --- .github/actions/install/action.yml | 21 +++++ .github/actions/lint/action.yml | 18 ++++ .github/workflows/_base.yml | 40 --------- ...documentation.yml => ci.documentation.yml} | 6 ++ .github/workflows/ci.lint.yml | 33 +++++++ .github/workflows/ci.release.yml | 83 +++++++++++++++++ .github/workflows/ci.yml | 54 ----------- .prettierignore | 1 + Writerside/dcs.tree | 4 +- ...ld-test-deploy-Writerside-documentation.md | 2 +- Writerside/topics/Workflows.md | 68 ++++++++++++++ Writerside/topics/starter-topic.md | 89 +------------------ src/semantic-release/index.js | 1 + 13 files changed, 237 insertions(+), 183 deletions(-) create mode 100644 .github/actions/install/action.yml create mode 100644 .github/actions/lint/action.yml delete mode 100644 .github/workflows/_base.yml rename .github/workflows/{documentation.yml => ci.documentation.yml} (92%) create mode 100644 .github/workflows/ci.lint.yml create mode 100644 .github/workflows/ci.release.yml delete mode 100644 .github/workflows/ci.yml create mode 100644 Writerside/topics/Workflows.md diff --git a/.github/actions/install/action.yml b/.github/actions/install/action.yml new file mode 100644 index 0000000..ab1f094 --- /dev/null +++ b/.github/actions/install/action.yml @@ -0,0 +1,21 @@ +name: 'Install' +description: 'Sets up Node, and installs dependencies' + +runs: + using: 'composite' + steps: + - name: Set up Node.js + uses: actions/setup-node@v4 + with: + node-version: 20 + + - name: Install pnpm + shell: bash + run: | + npm install -g pnpm + + - name: Install dependencies + shell: bash + run: | + corepack enable + pnpm install diff --git a/.github/actions/lint/action.yml b/.github/actions/lint/action.yml new file mode 100644 index 0000000..7efa2d1 --- /dev/null +++ b/.github/actions/lint/action.yml @@ -0,0 +1,18 @@ +name: 'Lint Code' +description: 'Runs Commitlint, ESLint, and Prettier to ensure code quality.' + +runs: + using: 'composite' + steps: + - name: Run Commitlint + shell: bash + run: | + git log -1 --pretty=%B | pnpm exec commitlint + + - name: Run ESLint + shell: bash + run: pnpm eslint . --max-warnings=0 + + - name: Run Prettier + shell: bash + run: pnpm prettier --check . diff --git a/.github/workflows/_base.yml b/.github/workflows/_base.yml deleted file mode 100644 index ed2a7ac..0000000 --- a/.github/workflows/_base.yml +++ /dev/null @@ -1,40 +0,0 @@ -name: Setup Workflow - -on: - workflow_call: - inputs: - node_version: - type: string - required: true - -jobs: - setup: - runs-on: ubuntu-latest - - steps: - - name: Checkout repository - uses: actions/checkout@v3 - with: - token: ${{ secrets.GITHUB_TOKEN }} - fetch-depth: 0 - - - name: Setup Node.js - uses: actions/setup-node@v3 - with: - node-version: ${{ inputs.node_version}} - - - name: Install pnpm - run: npm install -g pnpm - - - name: Install dependencies with pnpm - run: pnpm install - env: - GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} - - - name: Cache pnpm store - uses: actions/cache@v3 - with: - path: ./.pnpm-store - key: ${{ runner.os }}-pnpm-${{ hashFiles('pnpm-lock.yaml') }} # Cache key based on OS and lockfile hash - restore-keys: | - ${{ runner.os }}-pnpm- diff --git a/.github/workflows/documentation.yml b/.github/workflows/ci.documentation.yml similarity index 92% rename from .github/workflows/documentation.yml rename to .github/workflows/ci.documentation.yml index 99d150a..f4761f1 100644 --- a/.github/workflows/documentation.yml +++ b/.github/workflows/ci.documentation.yml @@ -27,6 +27,12 @@ jobs: token: ${{ secrets.GITHUB_TOKEN }} # Ensure access to private repo fetch-depth: 0 + - name: Install Dependencies + uses: ./lib/actions/install-dependencies + + - name: Run Lint Checks + uses: ./.github/actions/lint + - name: Build docs using Writerside Docker builder uses: JetBrains/writerside-github-action@v4 with: diff --git a/.github/workflows/ci.lint.yml b/.github/workflows/ci.lint.yml new file mode 100644 index 0000000..0ca0a1c --- /dev/null +++ b/.github/workflows/ci.lint.yml @@ -0,0 +1,33 @@ +name: Code Quality + +permissions: + pull-requests: write + contents: write + pages: write + id-token: write + +concurrency: + group: 'code-quality-${{ github.ref }}' + cancel-in-progress: false + +on: + pull_request: + push: + branches: + - main + +jobs: + code-quality: + runs-on: ubuntu-latest + steps: + - name: Checkout repository + uses: actions/checkout@v4 + with: + token: ${{ secrets.GITHUB_TOKEN }} + fetch-depth: 0 + + - name: Install Dependencies + uses: ./.github/actions/install + + - name: Run Lint Checks + uses: ./.github/actions/lint diff --git a/.github/workflows/ci.release.yml b/.github/workflows/ci.release.yml new file mode 100644 index 0000000..675c4fd --- /dev/null +++ b/.github/workflows/ci.release.yml @@ -0,0 +1,83 @@ +name: Release Workflow + +permissions: + pull-requests: write + contents: write + pages: write + id-token: write + +on: + push: + branches: + - main + +jobs: + release: + runs-on: ubuntu-latest + steps: + - name: Checkout repository + uses: actions/checkout@v4 + with: + token: ${{ secrets.GITHUB_TOKEN }} # Ensure access to private repo + fetch-depth: 0 + + - name: Install Dependencies + uses: ./lib/actions/install-dependencies + + - name: Run Lint Checks + uses: ./.github/actions/lint + + - name: Build Assets + run: ${{ inputs.build-command }} + + - name: Run Semantic Release + id: semantic_release + env: + GITHUB_TOKEN: ${{ secrets.GH_TOKEN }} + run: npx semantic-release + + - name: Create Release Branch + if: success() && steps.semantic_release.outputs.nextRelease + run: | + VERSION=${{ steps.semantic_release.outputs.nextRelease.version }} + git checkout -b ${{ inputs.release-branch-prefix }}${VERSION} + + - name: Push Release Branch + if: success() && steps.semantic_release.outputs.nextRelease + env: + PAT: ${{ secrets.PAT_FORCE_PUSH }} + run: | + git config user.name "github-actions[bot]" + git config user.email "github-actions[bot]@users.noreply.github.com" + git remote set-url origin https://x-access-token:${PAT}@github.com/${{ github.repository }}.git + git push origin ${{ inputs.release-branch-prefix }}${VERSION} --force + + - name: Extract Version from package.json + id: extract_version + run: | + VERSION=$(jq -r .version package.json) + echo "version=$VERSION" >> $GITHUB_OUTPUT + + - name: Extract Changelog + id: changelog + run: | + CHANGELOG=$(awk '/^## \[/ {print; exit}' CHANGELOG.md) + echo "changelog=$CHANGELOG" >> $GITHUB_OUTPUT + + - name: Create Pull Request to Main + if: success() && steps.semantic_release.outputs.nextRelease + uses: peter-evans/create-pull-request@v5 + with: + token: ${{ secrets.GITHUB_TOKEN }} + title: 'chore/release: ${{ steps.extract_version.outputs.version }}' + body: | + This is an automated pull request for release version `${{ steps.extract_version.outputs.version }}`. + + **Changelog:** + ``` + ${{ steps.changelog.outputs.changelog }} + ``` + head: ${{ inputs.release-branch-prefix }}${{ steps.extract_version.outputs.version }} + base: main + commit-message: 'chore/release: ${{ steps.extract_version.outputs.version }} [skip ci]' + labels: ${{ inputs.release-label }} diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml deleted file mode 100644 index 7cb3be4..0000000 --- a/.github/workflows/ci.yml +++ /dev/null @@ -1,54 +0,0 @@ -name: Code Quality - -permissions: - pull-requests: write - contents: write - pages: write - id-token: write - -concurrency: - group: 'pages' - cancel-in-progress: false - -on: - pull_request: - push: - branches: - - main - -jobs: - code-quality: - runs-on: ubuntu-latest - steps: - - name: Checkout repository - uses: actions/checkout@v3 - with: - token: ${{ secrets.GITHUB_TOKEN }} - fetch-depth: 0 - - - name: Setup Node.js - uses: actions/setup-node@v3 - with: - node-version: 20 - - - name: Install pnpm - run: npm install -g pnpm - - - name: Install dependencies with pnpm - run: pnpm install - - - name: Run Commitlint - run: git log -1 --pretty=%B | pnpm exec commitlint - - - name: Run ESLint - run: pnpm eslint . --max-warnings=0 # Use pnpm - - - name: Run Prettier - run: pnpm prettier --check . # Use pnpm - - - name: Run Semantic Release - if: github.ref == 'refs/heads/main' - env: - NPM_TOKEN: ${{ secrets.NPM_TOKEN }} - GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} - run: npx semantic-release diff --git a/.prettierignore b/.prettierignore index 33b8c23..2d2c9dc 100644 --- a/.prettierignore +++ b/.prettierignore @@ -1,2 +1,3 @@ package-lock.json +package.json pnpm-lock.yaml diff --git a/Writerside/dcs.tree b/Writerside/dcs.tree index 98ce6b3..21516a1 100644 --- a/Writerside/dcs.tree +++ b/Writerside/dcs.tree @@ -7,6 +7,8 @@ start-page="starter-topic.md"> - + + + diff --git a/Writerside/topics/How-to-build-test-deploy-Writerside-documentation.md b/Writerside/topics/How-to-build-test-deploy-Writerside-documentation.md index 6c8de80..d30399b 100644 --- a/Writerside/topics/How-to-build-test-deploy-Writerside-documentation.md +++ b/Writerside/topics/How-to-build-test-deploy-Writerside-documentation.md @@ -2,7 +2,7 @@ Here's the revised guide with the updated assumption: --- -# How to Build, Test & Deploy Writerside Documentation +# Release Workflow In this guide, you will learn how to set up a **reusable GitHub Actions workflow** to build, test, and deploy Writerside documentation to GitHub Pages. The reusable workflow will be installed diff --git a/Writerside/topics/Workflows.md b/Writerside/topics/Workflows.md new file mode 100644 index 0000000..7e285ef --- /dev/null +++ b/Writerside/topics/Workflows.md @@ -0,0 +1,68 @@ +# Automated Release Workflow with `semantic-release` + +This repository utilizes a **reusable GitHub Actions workflow** to automate the release process +using `semantic-release`. This setup ensures consistent and efficient releases across multiple +projects. + +## Features + +- **Automated Versioning:** Automatically determines the next version based on commit messages. +- **Changelog Generation:** Generates and updates the `CHANGELOG.md` with release notes. +- **Release Branching:** Creates dedicated release branches for each version. +- **Pull Request Automation:** Automatically creates a PR from the release branch to `main` for + review and merging. +- **Asset Attachment:** Attaches build artifacts to GitHub Releases. + +## Setup Guide + +Follow these steps to integrate the reusable release workflow into your project. + +### 1. **Add Required Secrets** + +Ensure that your repository has the necessary secrets configured: + +1. **Navigate to Repository Settings:** + + - Go to your repository on GitHub. + - Click on **Settings**. + +2. **Add Secrets:** + - Go to **Secrets and variables** > **Actions** > **New repository secret**. + - Add the following secrets: + - `GH_TOKEN`: Your GitHub Personal Access Token with `repo` permissions. + - `PAT_FORCE_PUSH`: Your Personal Access Token with permissions to push to protected branches. + +### 2. **Create the Reusable Workflow** + +The reusable workflow is already defined in this repository at +`.github/workflows/reusable-release.yml`. If you're using this repository as the source, you can +skip this step. Otherwise, ensure that your reusable workflow is correctly defined and accessible. + +### 3. **Create an Invoking Workflow** + +Add a new workflow file in your repository to call the reusable release workflow. + +**File Path:** `.github/workflows/call-reusable-release.yml` + +**Content:** + +```yaml +name: Call Reusable Release Workflow + +on: + push: + branches: + - main + +jobs: + release: + uses: @kurocado-studio/style-guide/.github/workflows/reusable-release.yml + with: + node-version: '18' + build-command: 'npm run build' + release-branch-prefix: 'release-' + release-label: 'release' + secrets: + GH_TOKEN: ${{ secrets.GH_TOKEN }} + PAT_FORCE_PUSH: ${{ secrets.PAT_FORCE_PUSH }}# Workflows +``` diff --git a/Writerside/topics/starter-topic.md b/Writerside/topics/starter-topic.md index 12a05ac..57aa117 100644 --- a/Writerside/topics/starter-topic.md +++ b/Writerside/topics/starter-topic.md @@ -1,89 +1,4 @@ # About docs - - -## Add new topics - -You can create empty topics, or choose a template for different types of content that contains some -boilerplate structure to help you get started: - -![Create new topic options](new_topic_options.png){ width=290 }{border-effect=line} - -## Write content - -%product% supports two types of markup: Markdown and XML. When you create a new help article, you -can choose between two topic types, but this doesn't mean you have to stick to a single format. You -can author content in Markdown and extend it with semantic attributes or inject entire XML elements. - -## Inject XML - -For example, this is how you inject a procedure: - - - -

Start typing and select a procedure type from the completion suggestions:

- completion suggestions for procedure - - -

Press Tab or Enter to insert the markup.

- - - -## Add interactive elements - -### Tabs - -To add switchable content, you can make use of tabs (inject them by starting to type `tab` on a new -line): - - - - ![Alt Text](new_topic_options.png){ width=450 } - - - - ]]> - - - -### Collapsible blocks - -Apart from injecting entire XML elements, you can use attributes to configure the behavior of -certain elements. For example, you can collapse a chapter that contains non-essential information: - -#### Supplementary info {collapsible="true"} - -Content under a collapsible header will be collapsed by default, but you can modify the behavior by -adding the following attribute: `default-state="expanded"` - -### Convert selection to XML - -If you need to extend an element with more functions, you can convert selected content from Markdown -to semantic markup. For example, if you want to merge cells in a table, it's much easier to convert -it to XML than do this in Markdown. Position the caret anywhere in the table and press -Alt+Enter: - -Convert table to XML - -## Feedback and support - -Please report any issues, usability improvements, or feature requests to our -YouTrack project (you will need to -register). - -You are welcome to join our public Slack workspace. Before you -do, please read our -[Code of conduct](https://plugins.jetbrains.com/plugin/20158-writerside/docs/writerside-code-of-conduct.html). -We assume that you’ve read and acknowledged it before joining. - -You can also always email us at [writerside@jetbrains.com](mailto:writerside@jetbrains.com). - - - - Markup reference - Reorder topics in the TOC - Build and publish - Configure Search - - +Writerside adds this topic when you create a new documentation project. You can use it as a sandbox +to play with Writerside features, and remove it from the TOC when you don't need it anymore. diff --git a/src/semantic-release/index.js b/src/semantic-release/index.js index 1cb3014..576dc52 100644 --- a/src/semantic-release/index.js +++ b/src/semantic-release/index.js @@ -23,4 +23,5 @@ module.exports = { '@semantic-release/github', '@semantic-release/npm', ], + preset: 'conventionalcommits', };