chore(ci): add automated dev releases (#467)

this commit implements an initial workflow for dev releases for stencil
sass. it is capable of:

- generating a build based using the same logic as other ci workflows
- generating a dev build version
- invoking a publish action with the dev version & 'dev' tag

a new publish action is added that is capable of incrementing the
version of the package and publishing changes to npm has been added. the
intent is to reuse this in some capacity for production releases.

this commit also includes additional actions for building the project &
downloading/uploading archives. to date, ci has been rather simplistic
in this repo. however, it's planned to integrate these actions into
existing workflows once this has been added to `main`.

.github/workflows/actions/download-archive/action.yml

@@ -0,0 +1,20 @@
+name: 'Create Stencil Sass Archive Download'
+description: 'downloads and decompresses an archive from a previous job'
+inputs:
+  path:
+    description: 'location to decompress the archive to'
+  filename:
+    description: 'the name of the decompressed artifact'
+  name:
+    description: 'name of the archive to decompress'
+runs:
+  using: 'composite'
+  steps:
+    - uses: actions/download-artifact@6b208ae046db98c579e8a3aa621ab581ff575935 # v4.1.1
+      with:
+        name: ${{ inputs.name }}
+        path: ${{ inputs.path }}
+
+    - name: Extract Archive
+      run: unzip -q -o ${{ inputs.path }}/${{ inputs.filename }}
+      shell: bash

.github/workflows/actions/get-core-dependencies/action.yml

@@ -0,0 +1,17 @@
+name: 'Get Core Dependencies'
+description: 'sets the node version & initializes core dependencies'
+runs:
+  using: composite
+  steps:
+    # this overrides previous versions of the node runtime that was set.
+    # jobs that need a different version of the Node runtime should explicitly
+    # set their node version after running this step
+    - name: Use Node Version from Volta
+      uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1
+      with:
+        node-version-file: './package.json'
+        cache: 'npm'
+
+    - name: Install Dependencies
+      run: npm ci
+      shell: bash

.github/workflows/actions/publish-npm/action.yml

@@ -0,0 +1,60 @@
+name: 'Publish to NPM'
+description: 'Publish the package to the NPM registry'
+inputs:
+  version:
+    description: 'The type of version to release.'
+  tag:
+    description: 'The tag to publish to on NPM.'
+  token:
+    description: 'The NPM authentication token required to publish.'
+runs:
+  using: 'composite'
+  steps:
+    # Log the input from GitHub Actions for easy traceability
+    - name: Log Inputs
+      run: |
+        echo "Version: ${{ inputs.version }}"
+        echo "Tag: ${{ inputs.tag }}"
+      shell: bash
+
+    - name: Checkout Code
+      uses: actions/checkout@8e5e7e5ab8b370d6c329ec480221332ada57f0ab # v3.5.2
+
+    - name: Get Core Dependencies
+      uses: ./.github/workflows/actions/get-core-dependencies
+
+    - name: Download Build Archive
+      uses: ./.github/workflows/actions/download-archive
+      with:
+        name: stencil-sass
+        path: .
+        filename: stencil-sass-build.zip
+
+    # Remove the ZIP file after we've extracted it - we don't want this committed back to the repo
+    - name: Delete The Archive ZIP File
+      run: rm stencil-sass-build.zip
+      shell: bash
+
+    - name: Bump Version
+      run: npm version --no-git-tag-version ${{ inputs.version }}
+      shell: bash
+
+    # Log the git diff for easy debugging
+    - name: Log Generated Changes
+      run: git --no-pager diff
+      shell: bash
+
+    # Log the git status for easy debugging
+    - name: Log Status
+      run: git status
+      shell: bash
+
+    - name: Prepare NPM Token
+      run: echo //registry.npmjs.org/:_authToken=${NPM_TOKEN} > .npmrc
+      shell: bash
+      env:
+        NPM_TOKEN: ${{ inputs.token }}
+
+    - name: Publish to NPM
+      run: npm publish --tag ${{ inputs.tag }} --provenance
+      shell: bash

.github/workflows/actions/upload-archive/action.yml

@@ -0,0 +1,20 @@
+name: 'Create Stencil Sass Archive Upload'
+description: 'compresses and uploads an archive to be reused across jobs'
+inputs:
+  paths:
+    description: 'paths to files or directories to archive (recursive)'
+  output:
+    description: 'output file name'
+  name:
+    description: 'name of the archive to upload'
+runs:
+  using: 'composite'
+  steps:
+    - name: Create Archive
+      run: zip -q -r ${{ inputs.output }} ${{ inputs.paths }}
+      shell: bash
+
+    - uses: actions/upload-artifact@694cdabd8bdb0f10b2cea11669e1bf5453eed0a6 # v4.2.0
+      with:
+        name: ${{ inputs.name }}
+        path: ${{ inputs.output }}

.github/workflows/build.yml

@@ -0,0 +1,37 @@
+name: Build Stencil Sass
+
+on:
+  workflow_call:
+  # Make this a reusable workflow, no value needed
+  # https://docs.github.com/en/actions/using-workflows/reusing-workflows
+
+jobs:
+  build_stencil_sass:
+    name: Build Stencil Sass
+    runs-on: 'ubuntu-latest'
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
+        with:
+          # the pull_request_target event will consider the HEAD of `main` to be the SHA to use.
+          # attempt to use the SHA associated with a pull request and fallback to HEAD of `main`
+          ref: ${{ github.event_name == 'pull_request_target' && format('refs/pull/{0}/merge', github.event.number) || '' }}
+          persist-credentials: false
+
+      - name: Get Core Dependencies
+        uses: ./.github/workflows/actions/get-core-dependencies
+
+      - name: Stencil Sass Build
+        run: npm run build
+        shell: bash
+
+      - name: Unit Tests
+        run: npm test
+        shell: bash
+
+      - name: Upload Build Artifacts
+        uses: ./.github/workflows/actions/upload-archive
+        with:
+          name: stencil-sass
+          output: stencil-sass-build.zip
+          paths: ./dist/

.github/workflows/release-dev.yml

@@ -0,0 +1,52 @@
+name: 'Dev Release'
+
+on:
+  workflow_dispatch:
+  # Make this a reusable workflow, no value needed
+  # https://docs.github.com/en/actions/using-workflows/reusing-workflows
+
+jobs:
+  build_stencil_sass:
+    name: Build
+    uses: ./.github/workflows/build.yml
+
+  get_dev_version:
+    name: Get Dev Build Version
+    runs-on: ubuntu-latest
+    outputs:
+      dev-version: ${{ steps.generate-dev-version.outputs.DEV_VERSION }}
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
+
+      - name: Generate Dev Version
+        id: generate-dev-version
+        run: |
+          PKG_JSON_VERSION=$(cat package.json | jq -r '.version')
+          GIT_HASH=$(git rev-parse --short HEAD)
+
+          # A unique string to publish Stencil Sass under
+          # e.g. "2.1.0-dev.1677185104.7c87e34"
+          DEV_VERSION=$PKG_JSON_VERSION-dev.$(date +"%s").$GIT_HASH
+          
+          echo "Using version $DEV_VERSION"
+
+          # store a key/value pair in GITHUB_OUTPUT
+          # e.g. "DEV_VERSION=2.1.0-dev.1677185104.7c87e34"
+          echo "DEV_VERSION=$DEV_VERSION" >> $GITHUB_OUTPUT
+        shell: bash
+
+  release_sass_stencil:
+    name: Publish Dev Build
+    needs: [build_stencil_sass, get_dev_version]
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
+      - uses: ./.github/workflows/actions/publish-npm
+        with:
+          tag: dev
+          version: ${{ needs.get_dev_version.outputs.dev-version }}
+          token: ${{ secrets.NPM_TOKEN }}

RELEASE.md

@@ -0,0 +1,34 @@
+# Releasing Stencil Sass
+
+## Development Releases
+
+Development Releases (or "Dev Releases", "Dev Builds") are installable instances of Stencil Sass that are:
+- Published to the npm registry for distribution within and outside the Stencil team
+- Built using the same infrastructure as production releases, with less safety checks
+- Used to verify a fix or change to the project prior to a production release
+
+### How to Publish
+
+Only members of the Stencil team may create dev builds of Stencil Sass.
+To publish the package:
+1. Navigate to the [Stencil Sass Dev Release GitHub Action](https://github.com/ionic-team/stencil-sass/actions/workflows/release-dev.yml) in your browser.
+2. Select the 'Run Workflow' dropdown on the right hand side of the page
+3. The dropdown will ask you for a branch name to publish from. Any branch may be used here.
+4. Select 'Run Workflow'
+5. Allow the workflow to run. Upon completion, the output of the 'publish-npm' action will report the published version string.
+
+Following a successful run of the workflow, the package can be installed from the npm registry like any other package.
+
+### Publish Format
+
+Dev Builds are published to the NPM registry under the `@stencil/sass` scope.
+Unlike production builds, dev builds use a specially formatted version string to express its origins.
+Dev builds follow the format `BASE_VERSION-dev.EPOCH_DATE.SHA`, where:
+- `BASE_VERSION` is the latest production release changes to the build were based off of
+- `EPOCH_DATE` is the number of seconds since January 1st, 1970 in UTC
+- `SHA` is the git short SHA of the commit used in the release
+
+As an example: `2.1.0-dev.1677185104.7c87e34` was built:
+- With v2.1.0 as the latest production build at the time of the dev build
+- On Fri, 26 Jan 2024 13:48:17 UTC
+- With the commit `7c87e34`