Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 8 additions & 31 deletions .github/workflows/__shared-ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -8,13 +8,13 @@ on:
value: ${{ jobs.nodejs.outputs.build-artifact-id }}
package-tarball-artifact-id:
description: "The artifact ID of the uploaded package tarball"
value: ${{ jobs.package-test.outputs.package-tarball-artifact-id }}
value: ${{ jobs.nodejs.outputs.package-tarball-artifact-id }}

permissions: {}

jobs:
linter:
uses: hoverkraft-tech/ci-github-common/.github/workflows/linter.yml@3a27d31e9ccefbe9609cc9165017ed100ff34a22 # 0.38.0
uses: hoverkraft-tech/ci-github-common/.github/workflows/linter.yml@90211d735aa0289702ddbd7eb95b218020ccadad # 2.0.2
permissions:
actions: read
contents: read
Expand All @@ -28,43 +28,20 @@ jobs:
FILTER_REGEX_EXCLUDE=packages/theme/lib/**/*,packages/docs/build/**/*

nodejs:
uses: hoverkraft-tech/ci-github-nodejs/.github/workflows/continuous-integration.yml@df348077afa4e79725151d50606e9dc63f86dcb6 # 0.24.4
uses: hoverkraft-tech/ci-github-nodejs/.github/workflows/continuous-integration.yml@02a04ad25ceaacdf3b7200e45fb7fec07fadf4fa # 2.1.0
permissions:
contents: read
id-token: write
packages: read
pull-requests: write
security-events: write
with:
package: |
{
"test-project": "packages/docs",
"tests": "npm run build"
}
build: |
{
"artifact": ["packages/theme/lib", "packages/docs/build"]
}

package-test:
name: Package and verify Docusaurus theme
needs: [linter, nodejs]
runs-on: ubuntu-latest
outputs:
package-tarball-artifact-id: ${{ steps.package.outputs.package-tarball-artifact-id }}
permissions:
contents: read
steps:
- id: package
name: Create package tarball
uses: hoverkraft-tech/ci-github-nodejs/actions/package@df348077afa4e79725151d50606e9dc63f86dcb6 # 0.24.4
with:
working-directory: .
package-directory: packages/theme
build-artifact-id: ${{ needs.nodejs.outputs.build-artifact-id }}
build-artifact-path: /
version: ${{ github.ref_type == 'tag' && github.ref_name || '' }}

- name: Build docs with packaged theme
working-directory: packages/docs
env:
PACKAGE_TARBALL_PATH: ${{ steps.package.outputs.package-tarball-path }}
run: |
npm uninstall @hoverkraft/docusaurus-theme || true
npm install "${PACKAGE_TARBALL_PATH}"
npm run build
2 changes: 1 addition & 1 deletion .github/workflows/greetings.yml
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ permissions: {}

jobs:
greetings:
uses: hoverkraft-tech/ci-github-common/.github/workflows/greetings.yml@3a27d31e9ccefbe9609cc9165017ed100ff34a22 # 0.38.0
uses: hoverkraft-tech/ci-github-common/.github/workflows/greetings.yml@90211d735aa0289702ddbd7eb95b218020ccadad # 2.0.2
permissions:
contents: read
issues: write
Expand Down
17 changes: 2 additions & 15 deletions .github/workflows/main-ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,6 @@ name: Internal - Main - Continuous Integration
on:
push:
branches: [main]
tags: ["*"]

permissions: {}

Expand All @@ -13,7 +12,7 @@ concurrency:

jobs:
ci:
uses: ./.github/workflows/__shared-ci.yml
uses: $/.github/workflows/__shared-ci.yml
permissions:
actions: read
contents: read
Expand All @@ -24,18 +23,6 @@ jobs:
security-events: write
statuses: write

npm-publish:
name: Publish package to npm
needs: ci
if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/')
uses: hoverkraft-tech/ci-github-nodejs/.github/workflows/release.yml@df348077afa4e79725151d50606e9dc63f86dcb6 # 0.24.4
permissions:
contents: read
packages: write
id-token: write
with:
package-tarball-artifact-id: ${{ needs.ci.outputs.package-tarball-artifact-id }}

deploy:
if: github.ref_name == github.event.repository.default_branch
name: Deploy website
Expand All @@ -51,7 +38,7 @@ jobs:
page-url: ${{ steps.deployment.outputs.url }}
steps:
- id: deployment
uses: hoverkraft-tech/ci-github-publish/actions/deploy/github-pages@1ee0354c40e4cd0a46c69cbe305c74fc67338042 # 0.28.0
uses: hoverkraft-tech/ci-github-publish/actions/deploy/github-pages@b942fb00f3115ca70f98f45f2289cc9838eb9312 # 3.0.0
with:
build-path: packages/docs/build
build-artifact-id: ${{ needs.ci.outputs.build-artifact-id }}
2 changes: 1 addition & 1 deletion .github/workflows/need-fix-to-issue.yml
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ permissions: {}

jobs:
main:
uses: hoverkraft-tech/ci-github-common/.github/workflows/need-fix-to-issue.yml@3a27d31e9ccefbe9609cc9165017ed100ff34a22 # 0.38.0
uses: hoverkraft-tech/ci-github-common/.github/workflows/need-fix-to-issue.yml@90211d735aa0289702ddbd7eb95b218020ccadad # 2.0.2
permissions:
contents: read
issues: write
Expand Down
14 changes: 14 additions & 0 deletions .github/workflows/prepare-release.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
name: Prepare release labels

on:
pull_request:
types: [opened, reopened, synchronize, edited]

permissions: {}

jobs:
prepare:
uses: hoverkraft-tech/ci-github-publish/.github/workflows/prepare-release.yml@b942fb00f3115ca70f98f45f2289cc9838eb9312 # 3.0.0
permissions:
contents: read
pull-requests: write
2 changes: 1 addition & 1 deletion .github/workflows/pull-request-ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ permissions: {}

jobs:
ci:
uses: ./.github/workflows/__shared-ci.yml
uses: $/.github/workflows/__shared-ci.yml
permissions:
actions: read
contents: read
Expand Down
60 changes: 60 additions & 0 deletions .github/workflows/release.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,60 @@
name: Release

on:
# checkov:skip=CKV_GHA_7:Force selects a committed release version; it cannot change build commands or bypass package validation.
workflow_dispatch:
inputs:
force:
description: Release the package even without changes
type: boolean
default: false
schedule:
- cron: "25 8 * * 1"

permissions: {}

concurrency:
group: release-${{ github.repository }}
cancel-in-progress: false

jobs:
prepare:
uses: hoverkraft-tech/ci-github-nodejs/.github/workflows/prepare-package-release.yml@02a04ad25ceaacdf3b7200e45fb7fec07fadf4fa # 2.1.0
permissions:
actions: write
contents: write
pull-requests: read
with:
package-directory: packages/theme
force: ${{ github.event_name == 'workflow_dispatch' && inputs.force }}
github-app-client-id: ${{ vars.CI_BOT_APP_CLIENT_ID }}
secrets:
github-app-key: ${{ secrets.CI_BOT_APP_PRIVATE_KEY }}

validate:
needs: prepare
if: needs.prepare.outputs.status == 'ready'
uses: $/.github/workflows/__shared-ci.yml
permissions:
actions: read
contents: read
packages: read
pull-requests: write
security-events: write
id-token: write
statuses: write
issues: write

release:
needs: [prepare, validate]
uses: hoverkraft-tech/ci-github-nodejs/.github/workflows/release.yml@02a04ad25ceaacdf3b7200e45fb7fec07fadf4fa # 2.1.0
permissions:
actions: read
contents: write
pull-requests: read
id-token: write
with:
packages: ${{ needs.prepare.outputs.packages }}
package-tarball-artifact-id: ${{ needs.validate.outputs.package-tarball-artifact-id }}
secrets:
changelog-summary: ${{ secrets.CHANGELOG_SUMMARY }}
5 changes: 2 additions & 3 deletions .github/workflows/semantic-pull-request.yml
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,6 @@ permissions: {}

jobs:
main:
uses: hoverkraft-tech/ci-github-common/.github/workflows/semantic-pull-request.yml@3a27d31e9ccefbe9609cc9165017ed100ff34a22 # 0.38.0
uses: hoverkraft-tech/ci-github-common/.github/workflows/semantic-pull-request.yml@90211d735aa0289702ddbd7eb95b218020ccadad # 2.0.2
permissions:
contents: write
pull-requests: write
contents: read
2 changes: 1 addition & 1 deletion .github/workflows/stale.yml
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ permissions: {}

jobs:
main:
uses: hoverkraft-tech/ci-github-common/.github/workflows/stale.yml@3a27d31e9ccefbe9609cc9165017ed100ff34a22 # 0.38.0
uses: hoverkraft-tech/ci-github-common/.github/workflows/stale.yml@90211d735aa0289702ddbd7eb95b218020ccadad # 2.0.2
permissions:
issues: write
pull-requests: write
2 changes: 1 addition & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -45,4 +45,4 @@ npm run start --workspace=@hoverkraft/hoverkraft-theme-docs # Launch docs for l

- Mirror any theme changes in `packages/docs/content` and `packages/docs/src` when user-facing behavior changes.
- Update `README.md` and relevant guide pages if interfaces, commands, or outputs change.
- Keep version bumps and changelog notes aligned with the release process defined in `README.md#releasing` once present.
- Keep version bumps and changelog notes aligned with the release process defined in [the release guide](docs/development/releasing.md).
7 changes: 2 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -75,12 +75,9 @@ make lint # Run linters
- Workspace test commands use the shared root `vitest.config.mts`. Run `npm test` to test both packages or `make test` to include coverage and JUnit reports.
- The docs site can be smoke-tested locally with `make start`.

## Releasing
## Maintainer documentation

1. Update semantic versioning in `packages/theme/package.json`.
2. Regenerate `packages/theme/lib` via `make build`.
3. Validate docs output with `make build` when content changes.
4. Publish the theme package via your chosen registry workflow (GitHub Actions or manual `npm publish`).
See the [documentation index](docs/README.md) for release setup and operation.

## Contributing

Expand Down
3 changes: 3 additions & 0 deletions docs/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
# Documentation

- [Releasing](development/releasing.md): maintainer setup, publication, and recovery.
58 changes: 58 additions & 0 deletions docs/development/releasing.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,58 @@
# Releasing

The [Release workflow](../../.github/workflows/release.yml) publishes `@hoverkraft/docusaurus-theme`.
It runs manually and weekly from `main`.

## Setup

1. Install the release GitHub App on this repository. Supply
`CI_BOT_APP_CLIENT_ID` as an Actions variable and `CI_BOT_APP_PRIVATE_KEY` as
an Actions secret, either directly or through organization access. The App
needs contents/actions write and pull requests read permissions. Branch and
tag rules must permit its version commits and tags; when PRs are required,
configure an Always allow bypass for this App.
2. Configure npm trusted publishing for `@hoverkraft/docusaurus-theme` with organization/user
`hoverkraft-tech`, repository `docusaurus-theme`, workflow filename `release.yml`,
and no environment restriction. Publication uses GitHub OIDC; npm tokens are
not used by this workflow.
3. Optionally set `CHANGELOG_SUMMARY` to the complete JSON configuration supported
by [ci-github-publish release/create](https://github.com/hoverkraft-tech/ci-github-publish/tree/main/actions/release/create),
including provider credentials when needed. Leaving it unset keeps generated
release notes without an AI summary.

## Run a release

Run **Actions > Release > Run workflow** on `main`. Leave `force` unchecked for
normal version planning. Check it to release even without changes; unchanged
versions receive a patch bump. Schedules never force a release.

Preparation updates package versions and the lockfile, commits them to `main`,
and creates the release tags before dispatching this workflow at the prepared
tag. HoverKraft selects the version from Conventional Commits and preserves the existing bare version tags.
With no changes, preparation ends successfully and skips building and publishing.

The tag run calls the same shared validation as pull requests. Package discovery
selects public workspaces automatically. CI builds, packs, validates entry points,
runs consumer smoke tests, and checks npm publication in dry-run mode. Release
then publishes those exact tarballs with provenance and creates GitHub release
notes and tarball assets. It does not rebuild or repack them, and does not write
source changelog files.

## Recovery

Rerun failed jobs, or dispatch **Release** at its original prepared tag. A tag run
resumes that version; it does not plan another one. Already published npm
versions are recovered from the registry and are never overwritten. For a source
fix, merge the fix and prepare a new release from `main`.

See the [shared release guide](https://github.com/hoverkraft-tech/ci-github-nodejs/blob/main/.github/workflows/release.md)
for configuration overrides and recovery details.

## Site deployment

Main CI continues to deploy the site after successful validation. The release
workflow publishes the npm package and GitHub release independently of Pages.

The separate `.github/workflows/prepare-release.yml` labels pull requests through
ci-github-publish. It runs when a PR opens or changes, including title edits.
Package version updates and publication remain in `.github/workflows/release.yml`.
2 changes: 1 addition & 1 deletion package-lock.json

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion packages/theme/package.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "@hoverkraft/docusaurus-theme",
"version": "1.0.0",
"version": "0.4.1",
"description": "Hoverkraft theme for Docusaurus",
"main": "lib/index.js",
"exports": {
Expand Down
Loading