Skip to content

Publish the styles as the @devexpress/vale-styles npm package - #10

Closed
AndreyKozhevnikov wants to merge 8 commits into
mainfrom
add-packages
Closed

AndreyKozhevnikov wants to merge 8 commits into
mainfrom
add-packages

Conversation

@AndreyKozhevnikov

@AndreyKozhevnikov AndreyKozhevnikov commented Oct 23, 2026 •

Copy link
Copy Markdown
Collaborator

vNext wants to run Vale on its whole documentation repository and keep the check green. To do that, it needs to take rules from this repository by version instead of copying them. This PR publishes the styles to GitHub Packages as @devexpress/vale-styles. Each package version is tied to a Vale version through an optional peer dependency. The vale/ folder layout does not change, so teams that copy it are not affected.

Changes

  • Package (package.json): @devexpress/vale-styles@1.0.0, published to npm.pkg.github.com. It ships dist/ and THIRD_PARTY_NOTICES.md (the MIT attribution for the Microsoft rules).
    • @vvago/vale ~3.25.1 is an optional peer dependency (peerDependenciesMeta). It's an npm wrapper that downloads the Vale binary in a postinstall script. If a consumer installs it, npm checks its version. npm doesn't install it on its own, so consumers who run Vale from a Docker image or another source don't download a second binary.
    • This repo pins 3.25.1 exactly as a dev dependency. allowScripts approves the wrapper's postinstall for npm 11.
  • Build (scripts/build.mjs, no dependencies): assembles dist/.
    • dist/DevExpress/ is a Vale package directory. styles/ is copied from vale/vale/styles/. .vale.ini is vale/.vale.ini without its StylesPath line, so vale/.vale.ini stays the only config to maintain.
    • dist/templates/ holds the JUnit and rdjsonl templates.
    • Consumers set Packages = node_modules/@devexpress/vale-styles/dist/DevExpress and run vale sync. Vale merges the package config underneath theirs.
  • Smoke test (scripts/smoke-test.mjs, npm test): builds the package and syncs it into a temporary consumer. It fails if any of the following happens:
    • Vale can't load a rule (exit code 2).
    • The merged config lacks DX, Microsoft or Vocab = DX.
    • The new vale/vale/tests/clean.md produces any alert.
    • A fixture's own rule never fires on it.
    • CLAUDE.md isn't skipped, or a consumer's own vocabulary doesn't combine with DX.
    • The npm pack file list differs from the expected one.
  • CI (.github/workflows/ci.yml): runs npm ci and npm test on pull requests and on pushes to main.
  • Release (.github/workflows/release.yml): runs on a vX.Y.Z tag, in two jobs.
    • test runs npm ci and npm test with a read-only token.
    • publish gets contents: write and packages: write and runs no third-party code: no install and no Vale binary. npm publish builds dist/ through prepack with the dependency-free build.mjs. Both checkouts use persist-credentials: false.
    • publish first checks the tag against package.json and CHANGELOG.md. For a stable tag, it also checks two things. The tagged commit must be in the first-parent history of main, so a commit from the PR branch fails even after the merge. The version must not be lower than the current latest dist-tag.
    • Then it publishes and creates a GitHub release from the changelog section.
    • A vX.Y.Z-rc.N tag on any commit publishes under the next dist-tag and creates a GitHub prerelease. The notes come from the ## X.Y.Z section, or from Unreleased if that section doesn't exist yet. npm 11 rejects prerelease publishes without an explicit --tag.
  • Docs:
    • README.md adds consumer setup:

      • .npmrc and a token for local installs
      • .vale.ini
      • a project vocabulary with its .gitignore pattern
      • a GitHub Actions workflow that uses GITHUB_TOKEN
      • upgrade steps

      It also adds sections on the version policy, development, releases, "Test a Release", and package visibility.

    • New CHANGELOG.md.

Reviewer notes

  • Version policy: this PR sets it for every future rule change. Any change that can raise new alerts on unchanged text is a major release: a new rule or swap entry, a stricter regex, a higher level, a removed vocabulary term, or a newer minimum Vale. Each rule change needs a CHANGELOG.md entry.
  • Release token isolation: keep npm ci, npm test and any other third-party code out of the publish job. Install scripts and the downloaded Vale binary must not run next to the write token. A comment at the top of release.yml says this.
  • Stable-tag checks haven't run yet: prerelease tags skip the "on main and not older than latest" step, so v1.0.0 is its first real run. If a check fails, nothing is published. Delete the tag and tag the correct commit (README, "Release a Version").
  • Package visibility: GitHub Packages creates a new package as private, and v1.0.0-rc.1 already created this one. An org owner must set its visibility to internal, or add each consumer repository under Manage Actions access.
  • @vvago/vale: a community wrapper with a single maintainer. It's pinned exactly and locked. The peer version check only covers consumers who install it from npm. Consumers who run Vale from a Docker image must match the version themselves.
  • After merging: tag v1.0.0 on the merge commit on main to publish. Because the tag goes on the merge commit, the 1.0.0 changelog date (2026-10-23) must be correct in this PR. Update it if the merge happens later. You can delete the v1.0.0-rc.1 and v1.0.0-rc.2 prereleases and package versions afterwards.

Testing

  • CI (npm test) passes on the PR head (5347d73).
  • Tag v1.0.0-rc.2 (5347d73 plus the version bump) ran release.yml. Both jobs passed, the workflow published @devexpress/vale-styles@1.0.0-rc.2 under next, and it created the GitHub prerelease. The stable-tag check was skipped, as designed for prereleases.
  • DevExpress/kozhevnikov-test installed 1.0.0-rc.2 in its Vale workflow using only its own GITHUB_TOKEN (packages: read, no stored secret). @vvago/vale@3.25.1 was deduped against the peer. The workflow linted a test page that covers every DX and Microsoft rule. Vale reported 43 errors and 27 warnings, matching the page's labels; the lint step fails on purpose. The only flagged Correct: line is a known Microsoft.Units case.
  • Local checks:
    • The smoke test fails as expected on a broken regex and on a violation added to clean.md.
    • Installing the packed 1.0.0 tarball with @vvago/vale@3.20.0 fails with ERESOLVE (conflicting peerOptional). The tarball on its own installs without @vvago/vale.

@AndreyKozhevnikov AndreyKozhevnikov changed the title [DRAFT] Add packages Publish the styles as the @devexpress/vale-styles npm package Oct 23, 2026
@AndreyKozhevnikov

AndreyKozhevnikov commented Oct 23, 2026 •

Copy link
Copy Markdown
Collaborator Author

@AndreyKozhevnikov
AndreyKozhevnikov requested review from SavchenkoAlexander and skudnoff and removed request for SavchenkoAlexander October 26, 2026 09:00
@AndreyKozhevnikov
AndreyKozhevnikov deleted the add-packages branch October 28, 2026 15:11
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant