From 25d0bf0072d09f85aac7083c6dd18bf4213af2c2 Mon Sep 17 00:00:00 2001 From: Dan Finn Date: Fri, 12 Dec 2025 13:48:43 -0500 Subject: [PATCH 1/6] expand readme --- README.md | 115 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 115 insertions(+) diff --git a/README.md b/README.md index be1f671..0de2315 100644 --- a/README.md +++ b/README.md @@ -13,11 +13,126 @@ Packages = https://github.com/digitalocean/vale-package/releases/latest/download See [Vale's documentation on packages](https://vale.sh/docs/topics/packages/) for more information. +## Package Structure + +The vale-package follows Vale's standard package structure and is organized as follows: + +``` +vale-package/ +├── styles/ +│ ├── DigitalOcean/ # Rules for general DigitalOcean style +│ ├── PDocs/ # Rules for Product Docs-specific style +│ ├── config/ +│ │ └── vocabularies/ # Accepted terminology lists +│ │ ├── DigitalOcean/ +│ │ ├── Technical/ +│ │ └── TechProperNouns/ +│ └── ignore/ # Words to ignore in spell checking +└── .vale.ini # Configuration file +``` + +### Styles + +#### DigitalOcean Style +Located in `styles/DigitalOcean/`, this style implements rules from the [DigitalOcean Style Guide](https://docs.digitalocean.com/style/digitalocean/). Each `.yml` file represents a specific rule that checks for style violations. + +**Key rules include:** +- **DigitalOceanTerms.yml** - Enforces correct capitalization and terminology for DigitalOcean products and services +- **Spelling.yml** - Spell checking with custom dictionary +- **SerialComma.yml** - Requires Oxford/serial commas +- **FutureTense.yml** - Discourages future tense in documentation +- **NumberCommas.yml** - Enforces comma formatting in numbers per Microsoft style guidelines +- **Units.yml** - Checks proper formatting of units of measurement +- **DateFormat.yml** - Enforces consistent date formatting + +#### PDocs Style +Located in `styles/PDocs/`, this style implements additional rules specific to the [Product Documentation Style Guide](https://docs.digitalocean.com/style/pdocs/). + +**Key rules include:** +- **Adverbs.yml** - Suggests removing unnecessary adverbs for clearer writing +- **Passive.yml** - Flags passive voice constructions +- **FirstPerson.yml** - Checks for inappropriate use of first person +- **Wordiness.yml** - Identifies wordy phrases with concise alternatives +- **ComplexWords.yml** - Suggests simpler alternatives to complex words + +### Vocabularies + +Vocabularies define accepted terms that should not be flagged as errors. Located in `styles/config/vocabularies/`: + +- **DigitalOcean/** - DigitalOcean-specific product names, features, and terminology +- **Technical/** - General technical terms accepted in our documentation +- **TechProperNouns/** - Proper nouns for technical brands, products, and services + +Vocabulary files use two lists: +- `accept.txt` - Terms accepted with this exact capitalization +- `reject.txt` - Terms that should never be used (often incorrect capitalizations) + +### Ignore Lists + +Located in `styles/ignore/`, these files contain words that should be ignored by spell checking: + +- **words-with-suggestions.txt** - Common compound words and technical terms that have valid alternatives but are acceptable (e.g., "webpage", "webserver", "multicore") + +These are separated from the main spelling checker because they have spelling suggestions but are valid in our documentation. + +## Rule Structure + +Each Vale rule file follows this general structure: + +```yaml +extends: [rule_type] # Base rule type (e.g., existence, substitution, spelling) +message: "..." # Error message shown to users +link: https://... # Link to relevant style guide section +level: error|warning|suggestion # Severity level +# Additional rule-specific properties +tokens: # Patterns to match + - pattern1 + - pattern2 +``` + +### Common Rule Types + +- **existence** - Checks for presence of specific words or patterns +- **substitution** - Suggests replacements using a swap map +- **spelling** - Spell checking against dictionaries +- **capitalization** - Enforces capitalization rules +- **occurrence** - Limits frequency of specific patterns + +## Maintenance + +### Adding New Terms + +1. **Product/brand names** → Add to `styles/config/vocabularies/DigitalOcean/accept.txt` +2. **General technical terms** → Add to `styles/config/vocabularies/Technical/accept.txt` +3. **Technical proper nouns** → Add to `styles/config/vocabularies/TechProperNouns/accept.txt` +4. **Compound words with valid alternatives** → Add to `styles/ignore/words-with-suggestions.txt` + +### Creating New Rules + +1. Create a new `.yml` file in `styles/DigitalOcean/` or `styles/PDocs/` +2. Follow the rule structure pattern shown above +3. Include a `link` to the relevant style guide section +4. Test the rule against sample documentation +5. Set appropriate severity level based on the style guide + +### Testing Rules + +Test your rules locally by running Vale against sample documentation: + +```bash +vale /path/to/test/file.md +``` + ## Included Components * The `DigitalOcean` style implements the [DigitalOcean style guide](https://docs.digitalocean.com/style/digitalocean/). * The `PDocs` style implements the [DigitalOcean Product Docs style guide](https://docs.digitalocean.com/style/pdocs/). * The `DigitalOcean` vocab implements DigitalOcean-specific terminology. * The `Technical` vocab implements more general technical terminology. +* The `TechProperNouns` vocab implements proper nouns for technical products and services. + +## Style Guide Mapping There are also a significant number of words defined in `.github/vale/ignore`, including notably a set of words with spelling suggestions which we want to catch with one of the package rules rather than with the less helpful spellchecker. + +Each Vale rule corresponds to specific sections in the [DigitalOcean Style Guide](https://docs.digitalocean.com/style/). The `link` property in each rule file points to the relevant style guide page for reference. From 3d9ff0d14105be6489824d26e171ff5f60451bfa Mon Sep 17 00:00:00 2001 From: Dan Finn Date: Mon, 15 Dec 2025 11:24:41 -0500 Subject: [PATCH 2/6] update readme and add Jira to list of accepted terms --- README.md | 52 ++++++++++++++----- .../vocabularies/TechProperNouns/accept.txt | 1 + 2 files changed, 39 insertions(+), 14 deletions(-) diff --git a/README.md b/README.md index 0de2315..2e21e29 100644 --- a/README.md +++ b/README.md @@ -4,15 +4,26 @@ This repository contains a [Vale-compatible](https://vale.sh/) implementation of ## Getting Started -To get started, add the package to your configuration file (as shown below) and then run `vale sync`. +Add the package to your configuration file and run `vale sync`. ```ini -StylesPath = styles # Use your normal style path here. +StylesPath = styles Packages = https://github.com/digitalocean/vale-package/releases/latest/download/do-vale.zip + +Vocab = DigitalOcean, Technical, TechProperNouns + +[*.md] +BasedOnStyles = Vale, DigitalOcean, PDocs ``` See [Vale's documentation on packages](https://vale.sh/docs/topics/packages/) for more information. +### Integration with product-docs + +The [product-docs repository](https://github.com/digitalocean/product-docs) uses this vale-package in its CI pipeline. The `product-docs/.vale.ini` references this package via the `Packages` directive. On each PR, GitHub Actions runs Vale, which downloads the latest package release and checks all modified Markdown files against the rules. Vale posts results as inline comments on the PR using reviewdog. + +Repositories can disable specific rules in their local `.vale.ini` where there are valid exceptions. This architecture lets the vale-package be maintained independently and reused across multiple DigitalOcean documentation repositories. + ## Package Structure The vale-package follows Vale's standard package structure and is organized as follows: @@ -102,22 +113,26 @@ tokens: # Patterns to match ### Adding New Terms -1. **Product/brand names** → Add to `styles/config/vocabularies/DigitalOcean/accept.txt` -2. **General technical terms** → Add to `styles/config/vocabularies/Technical/accept.txt` -3. **Technical proper nouns** → Add to `styles/config/vocabularies/TechProperNouns/accept.txt` -4. **Compound words with valid alternatives** → Add to `styles/ignore/words-with-suggestions.txt` +Add new terms to the appropriate vocabulary file: + +- **Product/brand names**: `styles/config/vocabularies/DigitalOcean/accept.txt` +- **General technical terms**: `styles/config/vocabularies/Technical/accept.txt` +- **Technical proper nouns**: `styles/config/vocabularies/TechProperNouns/accept.txt` +- **Compound words with valid alternatives**: `styles/ignore/words-with-suggestions.txt` ### Creating New Rules -1. Create a new `.yml` file in `styles/DigitalOcean/` or `styles/PDocs/` -2. Follow the rule structure pattern shown above -3. Include a `link` to the relevant style guide section -4. Test the rule against sample documentation -5. Set appropriate severity level based on the style guide +To create a new rule: + +1. Create a `.yml` file in `styles/DigitalOcean/` or `styles/PDocs/`. +2. Follow the rule structure pattern shown above. +3. Include a `link` to the relevant style guide section. +4. Test the rule against sample documentation. +5. Set the severity level based on the style guide. ### Testing Rules -Test your rules locally by running Vale against sample documentation: +Test rules locally by running Vale against sample documentation: ```bash vale /path/to/test/file.md @@ -133,6 +148,15 @@ vale /path/to/test/file.md ## Style Guide Mapping -There are also a significant number of words defined in `.github/vale/ignore`, including notably a set of words with spelling suggestions which we want to catch with one of the package rules rather than with the less helpful spellchecker. - Each Vale rule corresponds to specific sections in the [DigitalOcean Style Guide](https://docs.digitalocean.com/style/). The `link` property in each rule file points to the relevant style guide page for reference. + +## Repository-Specific Overrides + +Repositories using this package can disable specific rules in their local `.vale.ini` when there are valid exceptions. For example, product-docs disables some rules that have valid use cases in support documentation: + +```ini +PDocs.FirstPerson = NO +PDocs.Passive = NO +``` + +Document the reasoning when disabling rules. diff --git a/styles/config/vocabularies/TechProperNouns/accept.txt b/styles/config/vocabularies/TechProperNouns/accept.txt index 65cfb0e..cac67fd 100644 --- a/styles/config/vocabularies/TechProperNouns/accept.txt +++ b/styles/config/vocabularies/TechProperNouns/accept.txt @@ -48,6 +48,7 @@ Icinga IPFire Istio iwantmyname +Jira Kafka Kaniko Kartograph From 776790aa748286d41c2cc1f69da6f7bfa798e4be Mon Sep 17 00:00:00 2001 From: Dan Finn Date: Mon, 15 Dec 2025 11:36:15 -0500 Subject: [PATCH 3/6] add en dash rule per https://github.com/digitalocean/vale-package/issues/9 --- styles/DigitalOcean/EnDashRanges.yml | 10 ++++++++++ 1 file changed, 10 insertions(+) create mode 100644 styles/DigitalOcean/EnDashRanges.yml diff --git a/styles/DigitalOcean/EnDashRanges.yml b/styles/DigitalOcean/EnDashRanges.yml new file mode 100644 index 0000000..73b7984 --- /dev/null +++ b/styles/DigitalOcean/EnDashRanges.yml @@ -0,0 +1,10 @@ +extends: existence +message: "Use an en dash (–) for ranges, not a hyphen: '%s'" +link: https://docs.digitalocean.com/style/digitalocean/grammar/hyphens +level: warning +nonword: true +tokens: + # Numeric ranges with hyphens (e.g., "1-10", "200-299") + - '\d+-\d+' + # Time ranges with hyphens (e.g., "9am-5pm", "2023-2024") + - '\d+(?:am|pm|AM|PM)?-\d+(?:am|pm|AM|PM)?' From 9a74dee8835683985f3fa3c096cb855faa693113 Mon Sep 17 00:00:00 2001 From: Dan Finn Date: Mon, 15 Dec 2025 13:48:13 -0500 Subject: [PATCH 4/6] add link text check rule --- styles/DigitalOcean/LinkText.yml | 11 +++++++++++ 1 file changed, 11 insertions(+) create mode 100644 styles/DigitalOcean/LinkText.yml diff --git a/styles/DigitalOcean/LinkText.yml b/styles/DigitalOcean/LinkText.yml new file mode 100644 index 0000000..6c1bc28 --- /dev/null +++ b/styles/DigitalOcean/LinkText.yml @@ -0,0 +1,11 @@ +extends: existence +message: "Don't use '%s' as link text. Use descriptive text that indicates where the link goes." +link: https://docs.digitalocean.com/style/digitalocean/language/link-text +level: error +nonword: true +tokens: + - '\[click here\]' + - '\[here\]' + - '\[read more\]' + - '\[learn more\]' + - '\[this link\]' From 1d95d75ea67cc6e3d65c681c6b2ee7e6371d1712 Mon Sep 17 00:00:00 2001 From: Dan Finn Date: Wed, 7 Jan 2026 16:23:19 -0500 Subject: [PATCH 5/6] add release info --- README.md | 25 ++++++++++++++++++++++++- 1 file changed, 24 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 2e21e29..255884a 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,7 @@ This repository contains a [Vale-compatible](https://vale.sh/) implementation of Add the package to your configuration file and run `vale sync`. ```ini -StylesPath = styles +StylesPath = styles # Use your normal style path here. Packages = https://github.com/digitalocean/vale-package/releases/latest/download/do-vale.zip Vocab = DigitalOcean, Technical, TechProperNouns @@ -53,6 +53,8 @@ Located in `styles/DigitalOcean/`, this style implements rules from the [Digital - **SerialComma.yml** - Requires Oxford/serial commas - **FutureTense.yml** - Discourages future tense in documentation - **NumberCommas.yml** - Enforces comma formatting in numbers per Microsoft style guidelines +- **EnDashRanges.yml** - Requires en dashes in numeric and date ranges +- **LinkText.yml** - Checks for descriptive link text instead of generic phrases - **Units.yml** - Checks proper formatting of units of measurement - **DateFormat.yml** - Enforces consistent date formatting @@ -150,6 +152,27 @@ vale /path/to/test/file.md Each Vale rule corresponds to specific sections in the [DigitalOcean Style Guide](https://docs.digitalocean.com/style/). The `link` property in each rule file points to the relevant style guide page for reference. +## Releasing Updates + +To release a new version of the vale-package: + +1. **Prepare the package**: Ensure all updates are committed to the `do-vale/` directory, which contains: + - `styles/` - All style rules and vocabularies + - `.vale.ini` - Package configuration file (note: files starting with `.` require toggling hidden file visibility in macOS Finder: `Cmd+Shift+.`) + +2. **Create the zip file**: Create `do-vale.zip` from the `do-vale/` directory contents. The zip should contain the directory structure shown in the Package Structure section. + +3. **Create a GitHub release**: Upload `do-vale.zip` to a new release on GitHub. GitHub automatically includes the repository source code alongside the uploaded zip file. + +4. **Version the release**: Follow semantic versioning for release tags. + +Consumers reference the package via the releases URL in their `.vale.ini` configuration: +```ini +Packages = https://github.com/digitalocean/vale-package/releases/latest/download/do-vale.zip +``` + +See [Vale's documentation on packages](https://vale.sh/docs/topics/packages/) for more information on package structure requirements. + ## Repository-Specific Overrides Repositories using this package can disable specific rules in their local `.vale.ini` when there are valid exceptions. For example, product-docs disables some rules that have valid use cases in support documentation: From e4c93388dd795d1f7b07ff6b72489e5a0f57c4f7 Mon Sep 17 00:00:00 2001 From: Dan Finn Date: Mon, 12 Jan 2026 14:08:11 -0500 Subject: [PATCH 6/6] update docs one more time --- README.md | 42 +++++++++++++++++++++++++++++++++--------- 1 file changed, 33 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 255884a..bcd075e 100644 --- a/README.md +++ b/README.md @@ -152,26 +152,50 @@ vale /path/to/test/file.md Each Vale rule corresponds to specific sections in the [DigitalOcean Style Guide](https://docs.digitalocean.com/style/). The `link` property in each rule file points to the relevant style guide page for reference. -## Releasing Updates +## Deployment -To release a new version of the vale-package: +The vale-package uses an automated GitHub Actions workflow to create releases. The workflow packages the `styles/` directory and `.vale.ini` file into `do-vale.zip` with the correct structure and publishes it as a GitHub release. -1. **Prepare the package**: Ensure all updates are committed to the `do-vale/` directory, which contains: - - `styles/` - All style rules and vocabularies - - `.vale.ini` - Package configuration file (note: files starting with `.` require toggling hidden file visibility in macOS Finder: `Cmd+Shift+.`) +### Automatic Deployment on Merge -2. **Create the zip file**: Create `do-vale.zip` from the `do-vale/` directory contents. The zip should contain the directory structure shown in the Package Structure section. +When a pull request is merged to the `main` branch, the workflow automatically: +- Determines the new version number by incrementing the patch version (e.g., 3.0.2 → 3.0.3) +- Creates a new git tag +- Packages `styles/` and `.vale.ini` into `do-vale.zip` with structure `do-vale/styles/` and `do-vale/.vale.ini` +- Creates a GitHub release with auto-generated release notes +- Marks the release as latest -3. **Create a GitHub release**: Upload `do-vale.zip` to a new release on GitHub. GitHub automatically includes the repository source code alongside the uploaded zip file. +This ensures every merge to `main` produces a new release without manual intervention. -4. **Version the release**: Follow semantic versioning for release tags. +### Manual Deployment + +For releases that require a specific version increment (minor or major versions), you can trigger the workflow manually: + +1. Go to the [Actions tab](https://github.com/digitalocean/vale-package/actions/workflows/vale-package-rel.yml) in this repository. +2. Click "Run workflow". +3. Select the version increment type: + - **patch**: Bug fixes and minor rule updates (3.0.2 → 3.0.3) - *default for automatic releases* + - **minor**: New rules or features (3.0.2 → 3.1.0) + - **major**: Breaking changes to rule behavior (3.0.2 → 4.0.0) +4. Click "Run workflow". + +### Version Guidelines + +Follow [semantic versioning](https://semver.org/): +- **Major version** (X.0.0): Breaking changes that require users to update their configurations +- **Minor version** (0.X.0): New rules or features that are backwards compatible +- **Patch version** (0.0.X): Bug fixes, rule tweaks, vocabulary additions (automatic on merge) + +Since most updates are incremental improvements, the automatic patch increment on merge handles the majority of releases. Use manual deployment only when introducing new features (minor) or breaking changes (major). + +### Package Distribution Consumers reference the package via the releases URL in their `.vale.ini` configuration: ```ini Packages = https://github.com/digitalocean/vale-package/releases/latest/download/do-vale.zip ``` -See [Vale's documentation on packages](https://vale.sh/docs/topics/packages/) for more information on package structure requirements. +The `/latest/download/` path always points to the most recent release, so consumers automatically get updates when they run `vale sync`. ## Repository-Specific Overrides