From dae17be8e064a5fbf79444659d64123e78b837dc Mon Sep 17 00:00:00 2001 From: Andrey Kozhevnikov <14300209+AndreyKozhevnikov@users.noreply.github.com> Date: Fri, 23 Oct 2026 14:41:19 +0400 Subject: [PATCH 1/8] add packages infra --- .github/workflows/ci.yml | 21 ++++ .github/workflows/release.yml | 46 +++++++++ .gitignore | 2 + CHANGELOG.md | 12 +++ README.md | 137 ++++++++++++++++++++++++++ package-lock.json | 176 ++++++++++++++++++++++++++++++++++ package.json | 38 ++++++++ scripts/build.mjs | 27 ++++++ scripts/smoke-test.mjs | 94 ++++++++++++++++++ vale/vale/tests/clean.md | 19 ++++ 10 files changed, 572 insertions(+) create mode 100644 .github/workflows/ci.yml create mode 100644 .github/workflows/release.yml create mode 100644 .gitignore create mode 100644 CHANGELOG.md create mode 100644 package-lock.json create mode 100644 package.json create mode 100644 scripts/build.mjs create mode 100644 scripts/smoke-test.mjs create mode 100644 vale/vale/tests/clean.md diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..418c25d --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,21 @@ +name: CI + +on: + pull_request: + push: + branches: [main] + +permissions: + contents: read + +jobs: + test: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v7 + - uses: actions/setup-node@v7 + with: + node-version: lts/* + cache: npm + - run: npm ci + - run: npm test diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml new file mode 100644 index 0000000..25c68ff --- /dev/null +++ b/.github/workflows/release.yml @@ -0,0 +1,46 @@ +name: Release + +# Publishes @devexpress/vale-styles to GitHub Packages when a maintainer pushes a vX.Y.Z tag. +on: + push: + tags: ['v*.*.*'] + +permissions: + contents: write + packages: write + +jobs: + publish: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v7 + - uses: actions/setup-node@v7 + with: + node-version: lts/* + registry-url: https://npm.pkg.github.com + scope: '@devexpress' + + - name: Check the tag against package.json and CHANGELOG.md + run: | + version="$(node -p "require('./package.json').version")" + if [ "v$version" != "$GITHUB_REF_NAME" ]; then + echo "::error::Tag $GITHUB_REF_NAME does not match package.json version $version." + exit 1 + fi + awk -v version="$version" '/^## / { printing = ($2 == version); next } printing' CHANGELOG.md > "$RUNNER_TEMP/notes.md" + if ! grep -q '[^[:space:]]' "$RUNNER_TEMP/notes.md"; then + echo "::error::CHANGELOG.md has no '## $version' section." + exit 1 + fi + + - run: npm ci + - run: npm test + + - run: npm publish + env: + NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + + - name: Create the GitHub release + run: gh release create "$GITHUB_REF_NAME" --title "$GITHUB_REF_NAME" --notes-file "$RUNNER_TEMP/notes.md" + env: + GH_TOKEN: ${{ github.token }} diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..b947077 --- /dev/null +++ b/.gitignore @@ -0,0 +1,2 @@ +node_modules/ +dist/ diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..5b68552 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,12 @@ +# Changelog + +This file lists the changes in each release of `@devexpress/vale-styles`. Releases follow the version policy in [README.md](README.md#version-policy): a change that can raise new alerts on existing text is a major release. + +Add entries under `Unreleased` as you make changes. When you release, rename `Unreleased` to the new version and date, and start a new empty `Unreleased` section. The release workflow uses the section for the version as the GitHub release notes, and it fails if that section is missing. + +## Unreleased + +## 1.0.0 - 2026-10-23 + +- First npm release. The package contains the DX style, the trimmed Microsoft style, the DX vocabulary, the shared Vale configuration, and the JUnit and rdjsonl output templates. +- Requires Vale 3.25 (`@vvago/vale ~3.25.1`). diff --git a/README.md b/README.md index f467a17..491f74b 100644 --- a/README.md +++ b/README.md @@ -5,3 +5,140 @@ This repository contains a [Vale-compatible](https://github.com/vale-cli/vale) i Refer to Vale documentation for getting started instructions: [Installation](https://docs.vale.sh/topics/installation). This repository includes Vale rules from [vale-cli/Microsoft](https://github.com/vale-cli/Microsoft) (MIT-licensed), which are based on the [Microsoft Writing Style Guide](https://github.com/MicrosoftDocs/microsoft-style-guide) (licensed under CC-BY-4.0). Refer to the following file for additional information: [THIRD_PARTY_NOTICES.md](/THIRD_PARTY_NOTICES.md). + +## Use the Styles as an npm Package + +The `@devexpress/vale-styles` package is published to GitHub Packages. Each package version contains the DX and Microsoft styles, the DX vocabulary, the shared Vale configuration, and output templates for CI. A package version is tied to a Vale version, so a documentation repository can pin both and upgrade them on its own schedule. + +### Install the Package + +1. Create a GitHub personal access token with the `read:packages` scope. GitHub Packages requires a token even for public packages. +2. Add an `.npmrc` file to the root of your documentation repository: + + ```ini + @devexpress:registry=https://npm.pkg.github.com + //npm.pkg.github.com/:_authToken=${GITHUB_PACKAGES_TOKEN} + ``` + + Store the token in the `GITHUB_PACKAGES_TOKEN` environment variable on your machine and in CI. +3. Install the package and Vale. Pin exact versions so that rule updates arrive only when you upgrade on purpose: + + ```sh + npm install --save-dev --save-exact @devexpress/vale-styles@1.0.0 @vvago/vale@3.25.1 + ``` + + The `@vvago/vale` package downloads the Vale binary in a `postinstall` script. If npm reports that the script is not approved, run `npm install-scripts approve @vvago/vale`. Do not install with `--ignore-scripts`. + +The package declares the Vale version it supports in `peerDependencies`. npm fails the installation if your Vale version does not match. This check works only when you run Vale from npm (`npx vale`). A Vale binary from another source (for example, a Docker image) skips it. + +### Configure Vale + +Add a `.vale.ini` file to the root of your repository: + +```ini +StylesPath = .vale/styles +Packages = node_modules/@devexpress/vale-styles/dist/DevExpress +``` + +The package supplies the rest of the configuration: the `DX` and `Microsoft` styles for Markdown and text files, the `DX` vocabulary, and the `suggestion` alert level. Settings in your `.vale.ini` file take priority over package settings. + +The `vale sync` command copies the styles to the `StylesPath` folder. Do not commit the copied files. Add the following lines to `.gitignore`: + +```gitignore +.vale/styles/* +``` + +#### Add Your Own Terms + +To accept product names and terms that the DX vocabulary does not include, create a vocabulary of your own. For example, add terms to `.vale/styles/config/vocabularies/vNext/accept.txt`, one case-sensitive regular expression per line, and list the vocabulary in `.vale.ini`: + +```ini +Vocab = vNext +``` + +Vale combines this vocabulary with the `DX` vocabulary from the package. To commit your vocabulary but not the copied styles, use the following `.gitignore` lines instead: + +```gitignore +.vale/styles/* +!.vale/styles/config/ +.vale/styles/config/* +!.vale/styles/config/vocabularies/ +.vale/styles/config/vocabularies/* +!.vale/styles/config/vocabularies/vNext/ +``` + +### Run Vale + +Copy the styles to `StylesPath` after you install or update the package, and then lint your documentation: + +```sh +npx vale sync +npx vale docs/ +``` + +The following GitLab CI job checks every file in the `docs` folder and reports alerts as JUnit test results: + +```yaml +vale: + image: node:lts + script: + - npm ci + - npx vale sync + - npx vale --output=node_modules/@devexpress/vale-styles/dist/templates/junit.tmpl docs/ > vale-report.xml + artifacts: + when: always + reports: + junit: vale-report.xml +``` + +The `GITHUB_PACKAGES_TOKEN` CI/CD variable must hold a token with the `read:packages` scope. The job also needs network access to GitHub, where `@vvago/vale` downloads the Vale binary. For reviewdog output, use `dist/templates/rdjsonl.tmpl` instead. + +### Upgrade the Styles + +1. Read the [CHANGELOG.md](CHANGELOG.md) entries between your version and the new one. +2. Update the `@devexpress/vale-styles` version in `package.json`. If the new version requires a different Vale version, update `@vvago/vale` as well. +3. Run `npm install`, `npx vale sync`, and Vale on all your documentation. +4. Fix new alerts in the same merge request, so that the check stays green. + +## Version Policy + +Package versions follow semantic versioning. A version number shows whether an upgrade can produce new alerts in text that has not changed: + +- **Major**: the upgrade can produce new alerts. Examples: a new rule or swap entry, a stricter regular expression, a higher alert level, a term removed from the vocabulary, a lower `MinAlertLevel`, or a newer minimum Vale version. +- **Minor**: the upgrade does not produce new alerts but adds something. Examples: new vocabulary terms, new output templates, or support for more Vale versions. +- **Patch**: the upgrade only fixes false positives or changes alert messages. + +## Develop the Styles + +Rules are in the `vale/` folder, which you can also copy to a repository instead of installing the package. Install the development tools and run the tests from the repository root: + +```sh +npm ci +npm test +``` + +The `npm test` command builds the package in the `dist/` folder, installs it in a temporary repository with `vale sync`, and checks the following: + +- Vale loads every rule and the merged configuration without errors. +- The sample in `vale/vale/tests/clean.md` produces no alerts. +- Each rule that has a test file in `vale/vale/tests/DX/` produces at least one alert for that file. +- Files such as `CLAUDE.md` are skipped, and a vocabulary of your own works next to the `DX` vocabulary. +- The package contains exactly the expected files. + +Add an entry to the `Unreleased` section of [CHANGELOG.md](CHANGELOG.md) for each change. State whether the change can produce new alerts. + +## Release a Version + +1. In a new branch, run `npm version --no-git-tag-version`. Use the [version policy](#version-policy) to choose the level. +2. In `CHANGELOG.md`, rename the `Unreleased` section to the new version and date (for example, `## 1.1.0 - 2026-11-02`), and add an empty `Unreleased` section above it. +3. Merge the pull request. +4. Tag the merge commit and push the tag: + + ```sh + git tag v1.1.0 + git push origin v1.1.0 + ``` + +The `Release` workflow checks that the tag matches the `package.json` version and that `CHANGELOG.md` has a section for it. The workflow then runs the tests, publishes the package to GitHub Packages, and creates a GitHub release with the changelog section as release notes. + +To support a different Vale version, update `@vvago/vale` in `devDependencies` and the `peerDependencies` range in `package.json`, and run `npm install` and `npm test`. A newer minimum Vale version requires a major release. diff --git a/package-lock.json b/package-lock.json new file mode 100644 index 0000000..2ae86d3 --- /dev/null +++ b/package-lock.json @@ -0,0 +1,176 @@ +{ + "name": "@devexpress/vale-styles", + "version": "1.0.0", + "lockfileVersion": 3, + "requires": true, + "packages": { + "": { + "name": "@devexpress/vale-styles", + "version": "1.0.0", + "license": "MIT", + "devDependencies": { + "@vvago/vale": "3.25.1" + }, + "peerDependencies": { + "@vvago/vale": "~3.25.1" + } + }, + "node_modules/@isaacs/fs-minipass": { + "version": "4.0.1", + "resolved": "https://registry.npmjs.org/@isaacs/fs-minipass/-/fs-minipass-4.0.1.tgz", + "integrity": "sha512-wgm9Ehl2jpeqP3zw/7mo3kRHFp5MEDhqAdwy1fTGkHAwnkGOVsgpvQhL8B5n1qlb01jV3n/bI0ZfZp5lWA1k4w==", + "dev": true, + "license": "ISC", + "dependencies": { + "minipass": "^7.0.4" + }, + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/@vvago/vale": { + "version": "3.25.1", + "resolved": "https://registry.npmjs.org/@vvago/vale/-/vale-3.25.1.tgz", + "integrity": "sha512-fD0xio58t+dEGpRmILZT3t36H2J3iq0Vw88NYIvxPP51GWzp+miag/rI7F3td0/9YZnlWnd8QoyR3n8PbiuJfw==", + "dev": true, + "hasInstallScript": true, + "license": "MIT", + "dependencies": { + "fs-extra": "^11.4.0", + "tar": "^7.5.15", + "yauzl": "^3.4.0" + }, + "bin": { + "vale": "bin/vale.cjs" + }, + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/chownr": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/chownr/-/chownr-3.0.0.tgz", + "integrity": "sha512-+IxzY9BZOQd/XuYPRmrvEVjF/nqj5kgT4kEq7VofrDoM1MxoRjEWkrCC3EtLi59TVawxTAn+orJwFQcrqEN1+g==", + "dev": true, + "license": "BlueOak-1.0.0", + "engines": { + "node": ">=18" + } + }, + "node_modules/fs-extra": { + "version": "11.4.1", + "resolved": "https://registry.npmjs.org/fs-extra/-/fs-extra-11.4.1.tgz", + "integrity": "sha512-KYAb4c9BJQI6QqGKthV68OHe0badztdXJWKo0WtBA9IuCFPTKvE5ZdUBglP833aMjhaSPNO4A5j/EkzZtGlKjA==", + "dev": true, + "license": "MIT", + "dependencies": { + "graceful-fs": "^4.2.0", + "jsonfile": "^6.0.1", + "universalify": "^2.0.0" + }, + "engines": { + "node": ">=14.14" + } + }, + "node_modules/graceful-fs": { + "version": "4.2.11", + "resolved": "https://registry.npmjs.org/graceful-fs/-/graceful-fs-4.2.11.tgz", + "integrity": "sha512-RbJ5/jmFcNNCcDV5o9eTnBLJ/HszWV0P73bc+Ff4nS/rJj+YaS6IGyiOL0VoBYX+l1Wrl3k63h/KrH+nhJ0XvQ==", + "dev": true, + "license": "ISC" + }, + "node_modules/jsonfile": { + "version": "6.2.1", + "resolved": "https://registry.npmjs.org/jsonfile/-/jsonfile-6.2.1.tgz", + "integrity": "sha512-zwOTdL3rFQ/lRdBnntKVOX6k5cKJwEc1HdilT71BWEu7J41gXIB2MRp+vxduPSwZJPWBxEzv4yH1wYLJGUHX4Q==", + "dev": true, + "license": "MIT", + "dependencies": { + "universalify": "^2.0.0" + }, + "optionalDependencies": { + "graceful-fs": "^4.1.6" + } + }, + "node_modules/minipass": { + "version": "7.1.3", + "resolved": "https://registry.npmjs.org/minipass/-/minipass-7.1.3.tgz", + "integrity": "sha512-tEBHqDnIoM/1rXME1zgka9g6Q2lcoCkxHLuc7ODJ5BxbP5d4c2Z5cGgtXAku59200Cx7diuHTOYfSBD8n6mm8A==", + "dev": true, + "license": "BlueOak-1.0.0", + "engines": { + "node": ">=16 || 14 >=14.17" + } + }, + "node_modules/minizlib": { + "version": "3.1.0", + "resolved": "https://registry.npmjs.org/minizlib/-/minizlib-3.1.0.tgz", + "integrity": "sha512-KZxYo1BUkWD2TVFLr0MQoM8vUUigWD3LlD83a/75BqC+4qE0Hb1Vo5v1FgcfaNXvfXzr+5EhQ6ing/CaBijTlw==", + "dev": true, + "license": "MIT", + "dependencies": { + "minipass": "^7.1.2" + }, + "engines": { + "node": ">= 18" + } + }, + "node_modules/pend": { + "version": "1.2.0", + "resolved": "https://registry.npmjs.org/pend/-/pend-1.2.0.tgz", + "integrity": "sha512-F3asv42UuXchdzt+xXqfW1OGlVBe+mxa2mqI0pg5yAHZPvFmY3Y6drSf/GQ1A86WgWEN9Kzh/WrgKa6iGcHXLg==", + "dev": true, + "license": "MIT" + }, + "node_modules/tar": { + "version": "7.5.22", + "resolved": "https://registry.npmjs.org/tar/-/tar-7.5.22.tgz", + "integrity": "sha512-MFO/QzvtAOmJbkhOaCTvbGcFN9L9b+JunIsDwaKljSOdcLMea3NJ1k9Usz/rjdfSXTq4dfzfeS7W4p4YOAAHeA==", + "dev": true, + "license": "BlueOak-1.0.0", + "dependencies": { + "@isaacs/fs-minipass": "^4.0.0", + "chownr": "^3.0.0", + "minipass": "^7.1.2", + "minizlib": "^3.1.0", + "yallist": "^5.0.0" + }, + "engines": { + "node": ">=18" + } + }, + "node_modules/universalify": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/universalify/-/universalify-2.0.1.tgz", + "integrity": "sha512-gptHNQghINnc/vTGIk0SOFGFNXw7JVrlRUtConJRlvaw6DuX0wO5Jeko9sWrMBhh+PsYAZ7oXAiOnf/UKogyiw==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">= 10.0.0" + } + }, + "node_modules/yallist": { + "version": "5.0.0", + "resolved": "https://registry.npmjs.org/yallist/-/yallist-5.0.0.tgz", + "integrity": "sha512-YgvUTfwqyc7UXVMrB+SImsVYSmTS8X/tSrtdNZMImM+n7+QTriRXyXim0mBrTXNeqzVF0KWGgHPeiyViFFrNDw==", + "dev": true, + "license": "BlueOak-1.0.0", + "engines": { + "node": ">=18" + } + }, + "node_modules/yauzl": { + "version": "3.4.0", + "resolved": "https://registry.npmjs.org/yauzl/-/yauzl-3.4.0.tgz", + "integrity": "sha512-jIH9yLR9wqr0wOS0TpBvo/g/2UgZH5qePVbjgRliiF0BYvOZyaBknKsF+x9Iht0O6sqgnB93rCICdOZFecJuDw==", + "dev": true, + "license": "MIT", + "dependencies": { + "pend": "~1.2.0" + }, + "engines": { + "node": ">=12" + } + } + } +} diff --git a/package.json b/package.json new file mode 100644 index 0000000..876ce51 --- /dev/null +++ b/package.json @@ -0,0 +1,38 @@ +{ + "name": "@devexpress/vale-styles", + "version": "1.0.0", + "description": "Vale styles that implement the DevExpress Writing Style Guide", + "keywords": [ + "vale", + "vale-style", + "style-guide", + "documentation", + "linter" + ], + "license": "MIT", + "repository": { + "type": "git", + "url": "git+https://github.com/DevExpress/vale-styles.git" + }, + "files": [ + "dist/", + "THIRD_PARTY_NOTICES.md" + ], + "scripts": { + "build": "node scripts/build.mjs", + "prepack": "npm run build", + "test": "node scripts/smoke-test.mjs" + }, + "peerDependencies": { + "@vvago/vale": "~3.25.1" + }, + "devDependencies": { + "@vvago/vale": "3.25.1" + }, + "allowScripts": { + "@vvago/vale": true + }, + "publishConfig": { + "registry": "https://npm.pkg.github.com" + } +} diff --git a/scripts/build.mjs b/scripts/build.mjs new file mode 100644 index 0000000..a0f4792 --- /dev/null +++ b/scripts/build.mjs @@ -0,0 +1,27 @@ +// Assembles the npm package contents in dist/ from the vale/ folder, which stays the source of truth. +// +// dist/DevExpress/ is a Vale package directory (https://docs.vale.sh/keys/packages): +// a .vale.ini next to a styles/ folder. Consumers list it in Packages and run `vale sync`. +import { cpSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'; +import { dirname, join } from 'node:path'; +import { fileURLToPath } from 'node:url'; + +const root = join(dirname(fileURLToPath(import.meta.url)), '..'); +const dist = join(root, 'dist'); +const pkg = join(dist, 'DevExpress'); + +rmSync(dist, { recursive: true, force: true }); + +cpSync(join(root, 'vale', 'vale', 'styles'), join(pkg, 'styles'), { recursive: true }); + +// StylesPath belongs to the consumer's config, so drop it from the shipped one. +const config = readFileSync(join(root, 'vale', '.vale.ini'), 'utf8') + .replace(/^StylesPath\s*=.*(\r?\n)+/m, ''); +writeFileSync(join(pkg, '.vale.ini'), config); + +mkdirSync(join(dist, 'templates')); +for (const template of ['junit.tmpl', 'rdjsonl.tmpl']) { + cpSync(join(root, 'vale', template), join(dist, 'templates', template)); +} + +console.log(`Built ${dist}`); diff --git a/scripts/smoke-test.mjs b/scripts/smoke-test.mjs new file mode 100644 index 0000000..a06e8f6 --- /dev/null +++ b/scripts/smoke-test.mjs @@ -0,0 +1,94 @@ +// Release gate. Builds the package, installs it into a throwaway consumer the way the README +// documents (Packages + `vale sync`), and checks that the rules load and behave. +import { spawnSync } from 'node:child_process'; +import { cpSync, mkdirSync, mkdtempSync, readdirSync, rmSync, statSync, writeFileSync } from 'node:fs'; +import { createRequire } from 'node:module'; +import { tmpdir } from 'node:os'; +import { basename, dirname, join } from 'node:path'; +import { fileURLToPath } from 'node:url'; + +const root = join(dirname(fileURLToPath(import.meta.url)), '..'); +const require = createRequire(import.meta.url); +const valePkg = require.resolve('@vvago/vale/package.json'); +const valeBin = join(dirname(valePkg), require(valePkg).bin.vale); + +const failures = []; +const check = (ok, message) => ok || failures.push(message); + +// Exit code 1 only means error-level alerts; 2 means Vale could not run (bad config, rule, or regex). +function vale(cwd, ...args) { + const result = spawnSync(process.execPath, [valeBin, '--no-global', ...args], { cwd, encoding: 'utf8' }); + if (result.status !== 0 && result.status !== 1) { + throw new Error(`vale ${args.join(' ')} exited with ${result.status}:\n${result.stdout}${result.stderr}`); + } + return result.stdout; +} + +const alerts = (cwd, ...files) => JSON.parse(vale(cwd, '--output=JSON', ...files)); + +spawnSync(process.execPath, [join(root, 'scripts', 'build.mjs')], { stdio: 'inherit' }); + +const consumer = mkdtempSync(join(tmpdir(), 'vale-styles-smoke-')); +try { + cpSync(join(root, 'dist'), join(consumer, 'node_modules', '@devexpress', 'vale-styles', 'dist'), { recursive: true }); + writeFileSync(join(consumer, '.vale.ini'), [ + 'StylesPath = styles', + 'Packages = node_modules/@devexpress/vale-styles/dist/DevExpress', + 'Vocab = Smoke', + '', + ].join('\n')); + mkdirSync(join(consumer, 'styles', 'config', 'vocabularies', 'Smoke'), { recursive: true }); + // Use a term that no fixture contains, or the vocabulary would hide fixture alerts too. + writeFileSync(join(consumer, 'styles', 'config', 'vocabularies', 'Smoke', 'accept.txt'), 'recurrent\n'); + + vale(consumer, 'sync'); + + const config = JSON.parse(vale(consumer, 'ls-config')); + const markdownStyles = config.SBaseStyles?.['*.{md,MD,TXT,txt}'] ?? []; + check(markdownStyles.includes('DX') && markdownStyles.includes('Microsoft'), + `Markdown files should use DX and Microsoft, got ${JSON.stringify(markdownStyles)}`); + check(config.Vocab?.includes('DX') && config.Vocab?.includes('Smoke'), + `Vocab should merge DX with the consumer's Smoke vocabulary, got ${JSON.stringify(config.Vocab)}`); + + const clean = alerts(consumer, join(root, 'vale', 'vale', 'tests', 'clean.md')); + for (const alert of Object.values(clean).flat()) { + check(false, `clean.md:${alert.Line} ${alert.Check}: ${alert.Message}`); + } + + // Each fixture is named after its rule, so that rule must fire at least once. + const fixtures = alerts(consumer, join(root, 'vale', 'vale', 'tests', 'DX')); + for (const file of readdirSync(join(root, 'vale', 'vale', 'tests', 'DX'))) { + const rule = `DX.${basename(file, '.md')}`; + const fired = Object.entries(fixtures).some(([path, list]) => basename(path) === file && list.some(a => a.Check === rule)); + check(fired, `${rule} did not fire on its fixture ${file}`); + } + + writeFileSync(join(consumer, 'CLAUDE.md'), "The Chart can't do this.\n"); + writeFileSync(join(consumer, 'vocab.md'), 'The Chart supports recurrent appointments.\n'); + const skipped = alerts(consumer, 'CLAUDE.md', 'vocab.md'); + check(Object.keys(skipped).length === 0, + `CLAUDE.md should be skipped and the consumer vocabulary should accept "recurrent", got ${JSON.stringify(skipped)}`); +} finally { + rmSync(consumer, { recursive: true, force: true }); +} + +// The published tarball must hold exactly the built package plus the license files. +const pack = spawnSync('npm pack --dry-run --json --ignore-scripts', { cwd: root, encoding: 'utf8', shell: true }); +const packed = new Set(JSON.parse(pack.stdout)[0].files.map(f => f.path)); +const stylesDir = join(root, 'vale', 'vale', 'styles'); +const styles = readdirSync(stylesDir, { recursive: true }) + .filter(path => statSync(join(stylesDir, path)).isFile()) + .map(path => `dist/DevExpress/styles/${path.replaceAll('\\', '/')}`); +const expected = [ + 'package.json', 'README.md', 'LICENSE', 'THIRD_PARTY_NOTICES.md', + 'dist/DevExpress/.vale.ini', 'dist/templates/junit.tmpl', 'dist/templates/rdjsonl.tmpl', + ...styles, +]; +for (const path of expected) check(packed.has(path), `Tarball is missing ${path}`); +for (const path of packed) check(expected.includes(path), `Tarball has unexpected file ${path}`); + +if (failures.length) { + console.error(`Smoke test failed:\n- ${failures.join('\n- ')}`); + process.exit(1); +} +console.log(`Smoke test passed: ${packed.size} files packed, ${vale(root, '--version').trim()}.`); diff --git a/vale/vale/tests/clean.md b/vale/vale/tests/clean.md new file mode 100644 index 0000000..64d584e --- /dev/null +++ b/vale/vale/tests/clean.md @@ -0,0 +1,19 @@ +# Bind the Grid to Data + +This sample must not trigger any rule. The smoke test (`npm test`) fails if Vale reports an alert for this file. + +The Grid displays data from a local array or a remote service. To bind the Grid to data, set the `dataSource` property: + +```js +const grid = new Grid(element, { dataSource: orders }); +``` + +## Data Source Types + +The Grid supports the following data source types: + +- A local array of objects. +- A remote service that returns JSON. +- A custom store that loads data on demand. + +Refer to the following topic for more information: [Data Binding](data-binding.md). From 2403168c5aeb4f85695f7deea72b97d8c5edb313 Mon Sep 17 00:00:00 2001 From: Andrey Kozhevnikov <14300209+AndreyKozhevnikov@users.noreply.github.com> Date: Fri, 23 Oct 2026 15:02:49 +0400 Subject: [PATCH 2/8] update readme --- README.md | 60 +++++++++++++++++++++++++++++++++++++++---------------- 1 file changed, 43 insertions(+), 17 deletions(-) diff --git a/README.md b/README.md index 491f74b..bbc4416 100644 --- a/README.md +++ b/README.md @@ -12,15 +12,19 @@ The `@devexpress/vale-styles` package is published to GitHub Packages. Each pack ### Install the Package -1. Create a GitHub personal access token with the `read:packages` scope. GitHub Packages requires a token even for public packages. -2. Add an `.npmrc` file to the root of your documentation repository: +1. Add an `.npmrc` file to the root of your documentation repository: ```ini @devexpress:registry=https://npm.pkg.github.com - //npm.pkg.github.com/:_authToken=${GITHUB_PACKAGES_TOKEN} ``` - Store the token in the `GITHUB_PACKAGES_TOKEN` environment variable on your machine and in CI. + Do not add a token to this file. GitHub Actions workflows authenticate with their own `GITHUB_TOKEN` (see [Run Vale in GitHub Actions](#run-vale-in-github-actions)). +2. GitHub Packages requires a token for every installation. To install the package on your machine, create a personal access token (classic) with the `read:packages` scope and add it to your user-level npm configuration once: + + ```sh + npm config set //npm.pkg.github.com/:_authToken= + ``` + 3. Install the package and Vale. Pin exact versions so that rule updates arrive only when you upgrade on purpose: ```sh @@ -76,29 +80,49 @@ npx vale sync npx vale docs/ ``` -The following GitLab CI job checks every file in the `docs` folder and reports alerts as JUnit test results: +To produce JUnit XML or reviewdog output for CI tools, add `--output=node_modules/@devexpress/vale-styles/dist/templates/junit.tmpl` or `--output=node_modules/@devexpress/vale-styles/dist/templates/rdjsonl.tmpl`. + +#### Run Vale in GitHub Actions + +The following workflow checks every file in the `docs` folder. It installs the package with the workflow's own `GITHUB_TOKEN`, so the repository does not need a stored secret: ```yaml -vale: - image: node:lts - script: - - npm ci - - npx vale sync - - npx vale --output=node_modules/@devexpress/vale-styles/dist/templates/junit.tmpl docs/ > vale-report.xml - artifacts: - when: always - reports: - junit: vale-report.xml +name: Docs style + +on: + pull_request: + push: + branches: [main] + +permissions: + contents: read + packages: read + +jobs: + vale: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v7 + - uses: actions/setup-node@v7 + with: + node-version: lts/* + registry-url: https://npm.pkg.github.com + scope: '@devexpress' + - run: npm ci + env: + NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + - run: npx vale sync + - run: npx vale docs/ ``` -The `GITHUB_PACKAGES_TOKEN` CI/CD variable must hold a token with the `read:packages` scope. The job also needs network access to GitHub, where `@vvago/vale` downloads the Vale binary. For reviewdog output, use `dist/templates/rdjsonl.tmpl` instead. +If `npm ci` fails with a 403 error, an owner of the `@devexpress/vale-styles` package must add your repository under **Manage Actions access** in the package settings. CI systems outside GitHub do not have a `GITHUB_TOKEN`. In such systems, store a personal access token with the `read:packages` scope as a secret and add it to the npm configuration before `npm ci` with the `npm config set` command shown in [Install the Package](#install-the-package). ### Upgrade the Styles 1. Read the [CHANGELOG.md](CHANGELOG.md) entries between your version and the new one. 2. Update the `@devexpress/vale-styles` version in `package.json`. If the new version requires a different Vale version, update `@vvago/vale` as well. 3. Run `npm install`, `npx vale sync`, and Vale on all your documentation. -4. Fix new alerts in the same merge request, so that the check stays green. +4. Fix new alerts in the same pull request, so that the check stays green. ## Version Policy @@ -141,4 +165,6 @@ Add an entry to the `Unreleased` section of [CHANGELOG.md](CHANGELOG.md) for eac The `Release` workflow checks that the tag matches the `package.json` version and that `CHANGELOG.md` has a section for it. The workflow then runs the tests, publishes the package to GitHub Packages, and creates a GitHub release with the changelog section as release notes. +GitHub Packages makes a new package private, even if the repository is public. After the first release, an organization owner must change the visibility of `@devexpress/vale-styles` to internal in the package settings, so that workflows in other DevExpress repositories can install it. + To support a different Vale version, update `@vvago/vale` in `devDependencies` and the `peerDependencies` range in `package.json`, and run `npm install` and `npm test`. A newer minimum Vale version requires a major release. From 7349685753273073ecc3cb324280424a7f9de831 Mon Sep 17 00:00:00 2001 From: Andrey Kozhevnikov <14300209+AndreyKozhevnikov@users.noreply.github.com> Date: Fri, 23 Oct 2026 15:19:13 +0400 Subject: [PATCH 3/8] info about prerelease --- .github/workflows/release.yml | 14 ++++++++++---- README.md | 17 +++++++++++++++++ 2 files changed, 27 insertions(+), 4 deletions(-) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 25c68ff..d838f79 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -1,6 +1,8 @@ name: Release # Publishes @devexpress/vale-styles to GitHub Packages when a maintainer pushes a vX.Y.Z tag. +# A prerelease tag (vX.Y.Z-rc.N) on any commit, not only main, publishes under the `next` +# dist-tag and creates a GitHub prerelease. Use it to test a release before merging. on: push: tags: ['v*.*.*'] @@ -27,20 +29,24 @@ jobs: echo "::error::Tag $GITHUB_REF_NAME does not match package.json version $version." exit 1 fi - awk -v version="$version" '/^## / { printing = ($2 == version); next } printing' CHANGELOG.md > "$RUNNER_TEMP/notes.md" + # A prerelease such as 1.1.0-rc.1 uses the notes of 1.1.0. + awk -v version="${version%%-*}" '/^## / { printing = ($2 == version); next } printing' CHANGELOG.md > "$RUNNER_TEMP/notes.md" if ! grep -q '[^[:space:]]' "$RUNNER_TEMP/notes.md"; then - echo "::error::CHANGELOG.md has no '## $version' section." + echo "::error::CHANGELOG.md has no '## ${version%%-*}' section." exit 1 fi - run: npm ci - run: npm test - - run: npm publish + # npm 11 refuses to publish a prerelease without an explicit dist-tag. + - run: npm publish --tag ${{ contains(github.ref_name, '-') && 'next' || 'latest' }} env: NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }} - name: Create the GitHub release - run: gh release create "$GITHUB_REF_NAME" --title "$GITHUB_REF_NAME" --notes-file "$RUNNER_TEMP/notes.md" + run: >- + gh release create "$GITHUB_REF_NAME" --title "$GITHUB_REF_NAME" --notes-file "$RUNNER_TEMP/notes.md" + ${{ contains(github.ref_name, '-') && '--prerelease' || '' }} env: GH_TOKEN: ${{ github.token }} diff --git a/README.md b/README.md index bbc4416..ddb4956 100644 --- a/README.md +++ b/README.md @@ -165,6 +165,23 @@ Add an entry to the `Unreleased` section of [CHANGELOG.md](CHANGELOG.md) for eac The `Release` workflow checks that the tag matches the `package.json` version and that `CHANGELOG.md` has a section for it. The workflow then runs the tests, publishes the package to GitHub Packages, and creates a GitHub release with the changelog section as release notes. +### Test a Release + +To check the release workflow, package permissions, or a consumer setup before you merge, publish a prerelease from your branch. The `Release` workflow publishes a prerelease version under the `next` npm tag, so it never becomes the `latest` version, and creates a GitHub prerelease. The release notes come from the `CHANGELOG.md` section of the base version (for example, `1.0.0` for `1.0.0-rc.1`). + +```sh +git switch --detach +npm version 1.0.0-rc.1 --no-git-tag-version +git commit -am "Release 1.0.0-rc.1" +git tag v1.0.0-rc.1 +git push origin v1.0.0-rc.1 +git switch - +``` + +The tag points to a commit that is not on any branch, so your branch keeps its version. To test the prerelease in a documentation repository, install the exact version in a branch of that repository: `npm install --save-dev --save-exact @devexpress/vale-styles@1.0.0-rc.1`. After the test, you can delete the prerelease version in the package settings and delete the GitHub prerelease. + +### Package Visibility + GitHub Packages makes a new package private, even if the repository is public. After the first release, an organization owner must change the visibility of `@devexpress/vale-styles` to internal in the package settings, so that workflows in other DevExpress repositories can install it. To support a different Vale version, update `@vvago/vale` in `devDependencies` and the `peerDependencies` range in `package.json`, and run `npm install` and `npm test`. A newer minimum Vale version requires a major release. From 29754871dfe5052c1e4e64bd3a153c112efbefaf Mon Sep 17 00:00:00 2001 From: Andrey Kozhevnikov <14300209+AndreyKozhevnikov@users.noreply.github.com> Date: Mon, 26 Oct 2026 10:48:09 +0400 Subject: [PATCH 4/8] update prerelease code --- .github/workflows/release.yml | 24 ++++++++++++++++++------ CHANGELOG.md | 2 +- README.md | 14 ++++++++------ 3 files changed, 27 insertions(+), 13 deletions(-) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index d838f79..071c75a 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -2,7 +2,8 @@ name: Release # Publishes @devexpress/vale-styles to GitHub Packages when a maintainer pushes a vX.Y.Z tag. # A prerelease tag (vX.Y.Z-rc.N) on any commit, not only main, publishes under the `next` -# dist-tag and creates a GitHub prerelease. Use it to test a release before merging. +# dist-tag and creates a GitHub prerelease. Use it to test a release before merging. A prerelease +# takes its notes from the CHANGELOG.md Unreleased section until the version has a section of its own. on: push: tags: ['v*.*.*'] @@ -29,11 +30,22 @@ jobs: echo "::error::Tag $GITHUB_REF_NAME does not match package.json version $version." exit 1 fi - # A prerelease such as 1.1.0-rc.1 uses the notes of 1.1.0. - awk -v version="${version%%-*}" '/^## / { printing = ($2 == version); next } printing' CHANGELOG.md > "$RUNNER_TEMP/notes.md" - if ! grep -q '[^[:space:]]' "$RUNNER_TEMP/notes.md"; then - echo "::error::CHANGELOG.md has no '## ${version%%-*}' section." - exit 1 + # A prerelease such as 1.1.0-rc.1 uses the notes of 1.1.0. If the changelog has no 1.1.0 + # section yet (a prerelease from a feature branch), it uses the Unreleased notes. + base="${version%%-*}" + notes() { + awk -v heading="$1" '/^## / { printing = ($2 == heading); next } printing' CHANGELOG.md > "$RUNNER_TEMP/notes.md" + grep -q '[^[:space:]]' "$RUNNER_TEMP/notes.md" + } + if ! notes "$base"; then + if [ "$version" = "$base" ]; then + echo "::error::CHANGELOG.md has no '## $base' section." + exit 1 + fi + if ! notes Unreleased; then + echo "::error::CHANGELOG.md has no '## $base' section and no entries under '## Unreleased'." + exit 1 + fi fi - run: npm ci diff --git a/CHANGELOG.md b/CHANGELOG.md index 5b68552..5e289b1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,7 +2,7 @@ This file lists the changes in each release of `@devexpress/vale-styles`. Releases follow the version policy in [README.md](README.md#version-policy): a change that can raise new alerts on existing text is a major release. -Add entries under `Unreleased` as you make changes. When you release, rename `Unreleased` to the new version and date, and start a new empty `Unreleased` section. The release workflow uses the section for the version as the GitHub release notes, and it fails if that section is missing. +Add entries under `Unreleased` as you make changes. When you release, rename `Unreleased` to the new version and date, and start a new empty `Unreleased` section. The release workflow uses the section for the version as the GitHub release notes, and it fails if that section is missing. A prerelease uses the `Unreleased` section if the section for its version is missing. ## Unreleased diff --git a/README.md b/README.md index ddb4956..0465312 100644 --- a/README.md +++ b/README.md @@ -167,18 +167,20 @@ The `Release` workflow checks that the tag matches the `package.json` version an ### Test a Release -To check the release workflow, package permissions, or a consumer setup before you merge, publish a prerelease from your branch. The `Release` workflow publishes a prerelease version under the `next` npm tag, so it never becomes the `latest` version, and creates a GitHub prerelease. The release notes come from the `CHANGELOG.md` section of the base version (for example, `1.0.0` for `1.0.0-rc.1`). +To check the release workflow, package permissions, or a consumer setup before you merge, publish a prerelease from your branch. The `Release` workflow publishes a prerelease version under the `next` npm tag, so it never becomes the `latest` version, and creates a GitHub prerelease. Use the version of the next release with an `-rc.N` suffix (for example, `1.1.0-rc.1`). + +The release notes come from the `CHANGELOG.md` section of the base version (for example, `1.1.0` for `1.1.0-rc.1`). If that section does not exist yet, for example in a feature branch, the notes come from the `Unreleased` section, which must contain at least one entry. ```sh git switch --detach -npm version 1.0.0-rc.1 --no-git-tag-version -git commit -am "Release 1.0.0-rc.1" -git tag v1.0.0-rc.1 -git push origin v1.0.0-rc.1 +npm version 1.1.0-rc.1 --no-git-tag-version +git commit -am "Release 1.1.0-rc.1" +git tag v1.1.0-rc.1 +git push origin v1.1.0-rc.1 git switch - ``` -The tag points to a commit that is not on any branch, so your branch keeps its version. To test the prerelease in a documentation repository, install the exact version in a branch of that repository: `npm install --save-dev --save-exact @devexpress/vale-styles@1.0.0-rc.1`. After the test, you can delete the prerelease version in the package settings and delete the GitHub prerelease. +The tag points to a commit that is not on any branch, so your branch keeps its version. To test the prerelease in a documentation repository, install the exact version in a branch of that repository: `npm install --save-dev --save-exact @devexpress/vale-styles@1.1.0-rc.1`. After the test, you can delete the prerelease version in the package settings and delete the GitHub prerelease. ### Package Visibility From f310489c0ad18096f95833b2ee8ee5c3be609d1a Mon Sep 17 00:00:00 2001 From: Andrey Kozhevnikov <14300209+AndreyKozhevnikov@users.noreply.github.com> Date: Mon, 26 Oct 2026 10:54:32 +0400 Subject: [PATCH 5/8] update readme about vale --- README.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 0465312..740f22b 100644 --- a/README.md +++ b/README.md @@ -151,6 +151,10 @@ The `npm test` command builds the package in the `dist/` folder, installs it in Add an entry to the `Unreleased` section of [CHANGELOG.md](CHANGELOG.md) for each change. State whether the change can produce new alerts. +### Change the Vale Version + +To support a different Vale version, update `@vvago/vale` in `devDependencies` and the `peerDependencies` range in `package.json`, and run `npm install` and `npm test`. A newer minimum Vale version requires a major release (see the [version policy](#version-policy)). + ## Release a Version 1. In a new branch, run `npm version --no-git-tag-version`. Use the [version policy](#version-policy) to choose the level. @@ -185,5 +189,3 @@ The tag points to a commit that is not on any branch, so your branch keeps its v ### Package Visibility GitHub Packages makes a new package private, even if the repository is public. After the first release, an organization owner must change the visibility of `@devexpress/vale-styles` to internal in the package settings, so that workflows in other DevExpress repositories can install it. - -To support a different Vale version, update `@vvago/vale` in `devDependencies` and the `peerDependencies` range in `package.json`, and run `npm install` and `npm test`. A newer minimum Vale version requires a major release. From e5fe1029fea6ec431fccc664e6cb0f2558ec9a2f Mon Sep 17 00:00:00 2001 From: Andrey Kozhevnikov <14300209+AndreyKozhevnikov@users.noreply.github.com> Date: Mon, 26 Oct 2026 11:01:00 +0400 Subject: [PATCH 6/8] isolate packages --- .github/workflows/release.yml | 28 +++++++++++++++++++++++----- README.md | 2 +- 2 files changed, 24 insertions(+), 6 deletions(-) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 071c75a..c3c0451 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -4,19 +4,40 @@ name: Release # A prerelease tag (vX.Y.Z-rc.N) on any commit, not only main, publishes under the `next` # dist-tag and creates a GitHub prerelease. Use it to test a release before merging. A prerelease # takes its notes from the CHANGELOG.md Unreleased section until the version has a section of its own. +# +# The test job runs third-party code (npm ci install scripts and the downloaded Vale binary), so it +# gets a read-only token. The publish job has write access and runs no third-party code: npm publish +# builds dist/ with the dependency-free scripts/build.mjs. Do not add install or test steps to it. on: push: tags: ['v*.*.*'] permissions: - contents: write - packages: write + contents: read jobs: + test: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v7 + with: + persist-credentials: false + - uses: actions/setup-node@v7 + with: + node-version: lts/* + - run: npm ci + - run: npm test + publish: + needs: test runs-on: ubuntu-latest + permissions: + contents: write + packages: write steps: - uses: actions/checkout@v7 + with: + persist-credentials: false - uses: actions/setup-node@v7 with: node-version: lts/* @@ -48,9 +69,6 @@ jobs: fi fi - - run: npm ci - - run: npm test - # npm 11 refuses to publish a prerelease without an explicit dist-tag. - run: npm publish --tag ${{ contains(github.ref_name, '-') && 'next' || 'latest' }} env: diff --git a/README.md b/README.md index 740f22b..f274997 100644 --- a/README.md +++ b/README.md @@ -167,7 +167,7 @@ To support a different Vale version, update `@vvago/vale` in `devDependencies` a git push origin v1.1.0 ``` -The `Release` workflow checks that the tag matches the `package.json` version and that `CHANGELOG.md` has a section for it. The workflow then runs the tests, publishes the package to GitHub Packages, and creates a GitHub release with the changelog section as release notes. +The `Release` workflow runs the tests in a job that has read-only access to the repository. A separate job, which installs no dependencies, then checks that the tag matches the `package.json` version and that `CHANGELOG.md` has a section for it, publishes the package to GitHub Packages, and creates a GitHub release with the changelog section as release notes. ### Test a Release From d267f706158cf36af869e426d69eaf22a971fe3c Mon Sep 17 00:00:00 2001 From: Andrey Kozhevnikov <14300209+AndreyKozhevnikov@users.noreply.github.com> Date: Mon, 26 Oct 2026 11:25:29 +0400 Subject: [PATCH 7/8] allow new tags from main only --- .github/workflows/release.yml | 24 ++++++++++++++++++++++++ README.md | 7 +++++++ 2 files changed, 31 insertions(+) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index c3c0451..3312e13 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -1,6 +1,8 @@ name: Release # Publishes @devexpress/vale-styles to GitHub Packages when a maintainer pushes a vX.Y.Z tag. +# A stable tag must point to a commit in the first-parent history of main (the merge commit of the +# release pull request), and its version must not be lower than the current `latest` version. # A prerelease tag (vX.Y.Z-rc.N) on any commit, not only main, publishes under the `next` # dist-tag and creates a GitHub prerelease. Use it to test a release before merging. A prerelease # takes its notes from the CHANGELOG.md Unreleased section until the version has a section of its own. @@ -38,6 +40,7 @@ jobs: - uses: actions/checkout@v7 with: persist-credentials: false + fetch-depth: 0 - uses: actions/setup-node@v7 with: node-version: lts/* @@ -69,6 +72,27 @@ jobs: fi fi + - name: Check that a stable tag is on main and not older than latest + if: ${{ !contains(github.ref_name, '-') }} + run: | + if ! grep -qx "$(git rev-parse HEAD)" <(git rev-list --first-parent origin/main); then + echo "::error::Tag $GITHUB_REF_NAME is not on the main branch. Tag the merge commit of the release pull request." + exit 1 + fi + version="${GITHUB_REF_NAME#v}" + # With no `latest` dist-tag yet, npm view prints nothing. A package that does not exist yet fails with E404. + if ! latest="$(npm view @devexpress/vale-styles dist-tags.latest 2>"$RUNNER_TEMP/view.log")"; then + grep -q E404 "$RUNNER_TEMP/view.log" || { cat "$RUNNER_TEMP/view.log" >&2; exit 1; } + fi + latest="${latest%%-*}" + if [ -n "$latest" ] && [ "$version" != "$latest" ] && + [ "$(printf '%s\n' "$version" "$latest" | sort -V | head -n 1)" = "$version" ]; then + echo "::error::$version is older than the latest version $latest. Publishing it would move the latest dist-tag back." + exit 1 + fi + env: + NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + # npm 11 refuses to publish a prerelease without an explicit dist-tag. - run: npm publish --tag ${{ contains(github.ref_name, '-') && 'next' || 'latest' }} env: diff --git a/README.md b/README.md index f274997..e086a85 100644 --- a/README.md +++ b/README.md @@ -169,6 +169,13 @@ To support a different Vale version, update `@vvago/vale` in `devDependencies` a The `Release` workflow runs the tests in a job that has read-only access to the repository. A separate job, which installs no dependencies, then checks that the tag matches the `package.json` version and that `CHANGELOG.md` has a section for it, publishes the package to GitHub Packages, and creates a GitHub release with the changelog section as release notes. +For a stable version, the workflow also checks that the tag points to the merge commit on `main`, not to a commit from the pull request branch, and that the version is not lower than the current `latest` version. If a check fails, the workflow publishes nothing. Delete the tag and tag the correct commit: + +```sh +git tag -d v1.1.0 +git push origin --delete v1.1.0 +``` + ### Test a Release To check the release workflow, package permissions, or a consumer setup before you merge, publish a prerelease from your branch. The `Release` workflow publishes a prerelease version under the `next` npm tag, so it never becomes the `latest` version, and creates a GitHub prerelease. Use the version of the next release with an `-rc.N` suffix (for example, `1.1.0-rc.1`). From 5347d736301d5da29e545ed1917debcdc95d3f43 Mon Sep 17 00:00:00 2001 From: Andrey Kozhevnikov <14300209+AndreyKozhevnikov@users.noreply.github.com> Date: Mon, 26 Oct 2026 11:53:45 +0400 Subject: [PATCH 8/8] make vale optional --- CHANGELOG.md | 2 +- README.md | 2 +- package-lock.json | 5 +++++ package.json | 5 +++++ 4 files changed, 12 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 5e289b1..80c7ecb 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,4 +9,4 @@ Add entries under `Unreleased` as you make changes. When you release, rename `Un ## 1.0.0 - 2026-10-23 - First npm release. The package contains the DX style, the trimmed Microsoft style, the DX vocabulary, the shared Vale configuration, and the JUnit and rdjsonl output templates. -- Requires Vale 3.25 (`@vvago/vale ~3.25.1`). +- Requires Vale 3.25. The optional peer dependency `@vvago/vale ~3.25.1` checks the version when you install Vale from npm. diff --git a/README.md b/README.md index e086a85..5cd6483 100644 --- a/README.md +++ b/README.md @@ -33,7 +33,7 @@ The `@devexpress/vale-styles` package is published to GitHub Packages. Each pack The `@vvago/vale` package downloads the Vale binary in a `postinstall` script. If npm reports that the script is not approved, run `npm install-scripts approve @vvago/vale`. Do not install with `--ignore-scripts`. -The package declares the Vale version it supports in `peerDependencies`. npm fails the installation if your Vale version does not match. This check works only when you run Vale from npm (`npx vale`). A Vale binary from another source (for example, a Docker image) skips it. +The package declares the Vale version it supports as an optional peer dependency. npm does not install Vale for you, but if `@vvago/vale` is installed, npm fails the installation when its version does not match. If you run a Vale binary from another source (for example, a Docker image), install only `@devexpress/vale-styles`. npm does not check the version of such a binary, so make sure it matches. ### Configure Vale diff --git a/package-lock.json b/package-lock.json index 2ae86d3..d0b7cb2 100644 --- a/package-lock.json +++ b/package-lock.json @@ -13,6 +13,11 @@ }, "peerDependencies": { "@vvago/vale": "~3.25.1" + }, + "peerDependenciesMeta": { + "@vvago/vale": { + "optional": true + } } }, "node_modules/@isaacs/fs-minipass": { diff --git a/package.json b/package.json index 876ce51..b8b7b6e 100644 --- a/package.json +++ b/package.json @@ -26,6 +26,11 @@ "peerDependencies": { "@vvago/vale": "~3.25.1" }, + "peerDependenciesMeta": { + "@vvago/vale": { + "optional": true + } + }, "devDependencies": { "@vvago/vale": "3.25.1" },