Skip to content
Closed
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
21 changes: 21 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
@@ -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
106 changes: 106 additions & 0 deletions .github/workflows/release.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,106 @@
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.
#
# 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: 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
fetch-depth: 0
- 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
# 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

- 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:
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"
${{ contains(github.ref_name, '-') && '--prerelease' || '' }}
env:
GH_TOKEN: ${{ github.token }}
2 changes: 2 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
node_modules/
dist/
12 changes: 12 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -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. A prerelease uses the `Unreleased` section if the section for its version 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. The optional peer dependency `@vvago/vale ~3.25.1` checks the version when you install Vale from npm.
191 changes: 191 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,3 +5,194 @@ 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. Add an `.npmrc` file to the root of your documentation repository:

```ini
@devexpress:registry=https://npm.pkg.github.com
```

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=<your-token>
```

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 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

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/
```

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
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/
```

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 pull 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.

### 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 <major|minor|patch> --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 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`).

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.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.1.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.
Loading
Loading