From 19a8a67892d146b2e4b1220ecd14ac774cafa6e4 Mon Sep 17 00:00:00 2001 From: Carlos Santiago <5726971+csantiago132@users.noreply.github.com> Date: Thu, 3 Oct 2024 13:23:43 -0500 Subject: [PATCH] feat(ci): adds github actions workflow --- .github/lib/dependencies.workflow.yml | 19 ++++ .github/lib/linter.workflow.yml | 42 +++++++++ .github/lib/release.workflow.yml | 87 ++++++++++++++++++ ...documentation.yml => ci.documentation.yml} | 0 .github/workflows/ci.lint.yml | 35 ++++++++ .github/workflows/ci.release.yml | 28 ++++++ .github/workflows/ci.yml | 54 ----------- 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 + 12 files changed, 286 insertions(+), 143 deletions(-) create mode 100644 .github/lib/dependencies.workflow.yml create mode 100644 .github/lib/linter.workflow.yml create mode 100644 .github/lib/release.workflow.yml rename .github/workflows/{documentation.yml => ci.documentation.yml} (100%) 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/lib/dependencies.workflow.yml b/.github/lib/dependencies.workflow.yml new file mode 100644 index 0000000..f0ad732 --- /dev/null +++ b/.github/lib/dependencies.workflow.yml @@ -0,0 +1,19 @@ +name: Dependencies Workflow + +on: + workflow_call: + +jobs: + install-dependencies: + runs-on: ubuntu-latest + steps: + - 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 diff --git a/.github/lib/linter.workflow.yml b/.github/lib/linter.workflow.yml new file mode 100644 index 0000000..e21206f --- /dev/null +++ b/.github/lib/linter.workflow.yml @@ -0,0 +1,42 @@ +name: Linter Workflow + +on: + workflow_call: + secrets: + GITHUB_TOKEN: + description: 'GitHub Token with necessary permissions' + required: true + +jobs: + code-quality: + runs-on: ubuntu-latest + + permissions: + pull-requests: write + contents: write + pages: write + id-token: write + + concurrency: + group: 'code-quality-${{ github.ref }}' + cancel-in-progress: false + + steps: + - name: Checkout repository + uses: actions/checkout@v3 + with: + token: ${{ secrets.GITHUB_TOKEN }} + fetch-depth: 0 + + - name: Calls Install Dependencies + uses: ./.github/lib/dependencies.workflow.yml + + - name: Run Commitlint + run: | + git log -1 --pretty=%B | pnpm exec commitlint + + - name: Run ESLint + run: pnpm eslint . --max-warnings=0 + + - name: Run Prettier + run: pnpm prettier --check . diff --git a/.github/lib/release.workflow.yml b/.github/lib/release.workflow.yml new file mode 100644 index 0000000..e71eb4d --- /dev/null +++ b/.github/lib/release.workflow.yml @@ -0,0 +1,87 @@ +name: Release Workflow + +on: + workflow_call: + inputs: + release-branch-prefix: + description: 'Prefix for release branches' + required: false + type: string + default: 'release-' + release-label: + description: 'Label to add to the release pull request' + required: false + type: string + default: 'release' + secrets: + GH_TOKEN: + description: 'GitHub Personal Access Token with repo permissions' + required: true + PAT_FORCE_PUSH: + description: 'Personal Access Token with permissions to push to protected branches' + required: true + +permissions: + pull-requests: write + contents: write + pages: write + id-token: write + +jobs: + release: + runs-on: ubuntu-latest + steps: + - 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/documentation.yml b/.github/workflows/ci.documentation.yml similarity index 100% rename from .github/workflows/documentation.yml rename to .github/workflows/ci.documentation.yml diff --git a/.github/workflows/ci.lint.yml b/.github/workflows/ci.lint.yml new file mode 100644 index 0000000..2bf802a --- /dev/null +++ b/.github/workflows/ci.lint.yml @@ -0,0 +1,35 @@ +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: Install Dependencies + uses: ./.github/lib/dependencies.workflow.yml + + - name: Code Quality + uses: ./.github/lib/linter.workflow.yml + + diff --git a/.github/workflows/ci.release.yml b/.github/workflows/ci.release.yml new file mode 100644 index 0000000..4e09ecf --- /dev/null +++ b/.github/workflows/ci.release.yml @@ -0,0 +1,28 @@ +name: Call Release Workflow + +on: + push: + branches: + - main + +jobs: + release: + runs-on: ubuntu-latest + steps: + - name: Checkout repository + uses: actions/checkout@v3 + with: + token: ${{ secrets.GITHUB_TOKEN }} + fetch-depth: 0 + + - name: Install Dependencies + uses: ./.github/lib/dependencies.workflow.yml + + - name: Release + uses: ./.github/lib/release.workflow.yml + with: + release-branch-prefix: 'release-' + release-label: 'release' + env: + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + PAT_FORCE_PUSH: ${{ secrets.GH_TOKEN }} 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/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', };