mirror of
https://github.com/lancedb/lancedb.git
synced 2026-10-29 14:56:51 +00:00
fix(ci): bundle Vale rules to avoid private release downloads (#4707)
The prose check fails because it downloads its Vale rules from the now-private docs repository. Keep the five unchanged rules from `vale-lancedb-v0.1.0` in this repository and disable `vale sync` in CI. This also works for contributors without access to the docs repository. The update instructions record the release and archive checksum.
This commit is contained in:
Brendan Clement
@@ -0,0 +1,17 @@
|
||||
# LanceDB prose rules
|
||||
|
||||
These five rule files are copied unchanged from the `LanceDB.zip` asset of
|
||||
`lancedb/docs` release `vale-lancedb-v0.1.0`. The archive SHA-256 is
|
||||
`0730a43e919774121068811d5687c61dfc7a0421cff78e1393f5e565b622cb0f`.
|
||||
|
||||
Keeping the rules here lets contributors and CI run Vale without access to the
|
||||
source repository. The root `.vale.ini` preserves the release's MDX settings
|
||||
and built-in repeated-word check. No `vale sync` is needed.
|
||||
|
||||
The rules check product names, dashes, plain language, vague headings and vague
|
||||
phrases. Findings are suggestions and do not fail the CI check.
|
||||
|
||||
To update, a maintainer downloads the next published package, verifies its
|
||||
checksum and replaces `styles/LanceDB` with the release's files. Check the
|
||||
package's `.vale.ini` for configuration changes, and update the version and
|
||||
checksum here in the same PR.
|
||||
@@ -0,0 +1,40 @@
|
||||
extends: existence
|
||||
message: "Avoid '%s' in prose. Use a comma, a colon, parentheses or two sentences."
|
||||
link: https://github.com/lancedb/docs/blob/main/STYLE.md#punctuation
|
||||
level: warning
|
||||
nonword: true
|
||||
# An em dash in prose, and a double hyphen or en dash used as one, with a
|
||||
# space on each side. A table cell holding only an em dash, meaning "none",
|
||||
# ranges such as 1–3 and flags such as --force are left alone, and code is
|
||||
# never prose.
|
||||
raw:
|
||||
- '(?<!^\s*)—|—(?!\s*$)|(?<=\s)(?:--|–)(?=\s|$)'
|
||||
tests:
|
||||
- name: flags an em dash
|
||||
input: Indexes are optional—queries work without them.
|
||||
want: |
|
||||
1:21:LanceDB.Dashes:Avoid '—' in prose. Use a comma, a colon, parentheses or two sentences.
|
||||
- name: flags a double hyphen used as a dash
|
||||
input: It has one page per statement, syntax first -- and every SDK operation has a SQL form.
|
||||
want: |
|
||||
1:45:LanceDB.Dashes:Avoid '--' in prose. Use a comma, a colon, parentheses or two sentences.
|
||||
- name: flags a spaced en dash
|
||||
input: Compaction is cheap – it rewrites only small fragments.
|
||||
want: |
|
||||
1:21:LanceDB.Dashes:Avoid '–' in prose. Use a comma, a colon, parentheses or two sentences.
|
||||
- name: leaves an empty table cell alone
|
||||
input: |
|
||||
| Provider | Text | Images |
|
||||
| --- | --- | --- |
|
||||
| OpenAI | ✓ | — |
|
||||
| Gemini | ✓ | per request — batched |
|
||||
want: |
|
||||
4:28:LanceDB.Dashes:Avoid '—' in prose. Use a comma, a colon, parentheses or two sentences.
|
||||
- name: leaves ranges, flags and code alone
|
||||
input: |
|
||||
Use 1–3 replicas and pass --force to overwrite. Run `lancedb --version`.
|
||||
|
||||
```bash
|
||||
uv run pytest -- -k search
|
||||
```
|
||||
want: ''
|
||||
@@ -0,0 +1,32 @@
|
||||
extends: substitution
|
||||
message: "Consider '%s' instead of '%s'."
|
||||
link: https://github.com/lancedb/docs/blob/main/STYLE.md#say-it-directly
|
||||
level: suggestion
|
||||
ignorecase: true
|
||||
# Keep this list small. Technical nouns such as GPU utilization stay intact.
|
||||
swap:
|
||||
utilize: use
|
||||
utilizes: uses
|
||||
utilized: used
|
||||
utilizing: using
|
||||
in order to: to
|
||||
tests:
|
||||
- name: suggests familiar verbs
|
||||
input: Utilize the index. The query utilizes it. We utilized it. Try utilizing it.
|
||||
want: |
|
||||
1:1:LanceDB.PlainLanguage:Consider 'use' instead of 'Utilize'.
|
||||
1:30:LanceDB.PlainLanguage:Consider 'uses' instead of 'utilizes'.
|
||||
1:46:LanceDB.PlainLanguage:Consider 'used' instead of 'utilized'.
|
||||
1:63:LanceDB.PlainLanguage:Consider 'using' instead of 'utilizing'.
|
||||
- name: shortens an unnecessary phrase
|
||||
input: Create an index in order to search faster.
|
||||
want: |
|
||||
1:17:LanceDB.PlainLanguage:Consider 'to' instead of 'in order to'.
|
||||
- name: preserves technical terms and identifiers
|
||||
input: |
|
||||
Measure GPU utilization and resource underutilization. Keep the rows in order. Call `utilize()` and `in order to` only as literal examples.
|
||||
|
||||
```python
|
||||
utilized = "in order to"
|
||||
```
|
||||
want: ''
|
||||
@@ -0,0 +1,34 @@
|
||||
extends: substitution
|
||||
message: "Use '%s' instead of '%s'."
|
||||
link: https://github.com/lancedb/docs/blob/main/STYLE.md#names
|
||||
level: warning
|
||||
ignorecase: false
|
||||
# Case-sensitive. A lowercase package, repository or domain name, such as
|
||||
# lancedb or github.com, is left alone; write identifiers in code font.
|
||||
swap:
|
||||
'(?:Lancedb|LanceDb|lanceDB|LANCEDB|Lance DB)': LanceDB
|
||||
'LanceDB (?:cloud|CLOUD)': LanceDB Cloud
|
||||
'LanceDB (?:enterprise|ENTERPRISE)': LanceDB Enterprise
|
||||
'LanceDB (?:oss|Oss)': LanceDB OSS
|
||||
'(?:HuggingFace|Huggingface|Hugging face)': Hugging Face
|
||||
Langchain: LangChain
|
||||
Typescript: TypeScript
|
||||
VoyageAI: Voyage AI
|
||||
tests:
|
||||
- name: corrects the product name
|
||||
input: Install Lancedb and connect to LanceDB cloud or LanceDB enterprise.
|
||||
want: |
|
||||
1:9:LanceDB.ProductNames:Use 'LanceDB' instead of 'Lancedb'.
|
||||
1:32:LanceDB.ProductNames:Use 'LanceDB Cloud' instead of 'LanceDB cloud'.
|
||||
1:49:LanceDB.ProductNames:Use 'LanceDB Enterprise' instead of 'LanceDB enterprise'.
|
||||
- name: corrects names seen misspelled in the current pages
|
||||
input: Load a HuggingFace model, build a Langchain retriever in Typescript and call VoyageAI.
|
||||
want: |
|
||||
1:8:LanceDB.ProductNames:Use 'Hugging Face' instead of 'HuggingFace'.
|
||||
1:35:LanceDB.ProductNames:Use 'LangChain' instead of 'Langchain'.
|
||||
1:58:LanceDB.ProductNames:Use 'TypeScript' instead of 'Typescript'.
|
||||
1:78:LanceDB.ProductNames:Use 'Voyage AI' instead of 'VoyageAI'.
|
||||
- name: leaves package names, identifiers and code alone
|
||||
input: |
|
||||
The lancedb package exposes `HuggingFaceEmbeddings` and LanceDBConnection; see `Typescript` in code.
|
||||
want: ''
|
||||
@@ -0,0 +1,19 @@
|
||||
extends: existence
|
||||
message: "'%s' doesn't say what the section covers. Name the task or topic instead."
|
||||
link: https://github.com/lancedb/docs/blob/main/STYLE.md#headings
|
||||
level: suggestion
|
||||
scope: heading
|
||||
ignorecase: true
|
||||
tokens:
|
||||
- then what
|
||||
tests:
|
||||
- name: flags a heading that names no topic
|
||||
input: |
|
||||
## Then what {#next}
|
||||
|
||||
Choose the output according to how you will use it.
|
||||
want: |
|
||||
1:4:LanceDB.VagueHeadings:'Then what' doesn't say what the section covers. Name the task or topic instead.
|
||||
- name: leaves the phrase alone in body text
|
||||
input: Then what happens to the old fragments? Cleanup removes them.
|
||||
want: ''
|
||||
@@ -0,0 +1,31 @@
|
||||
extends: existence
|
||||
message: "'%s' talks about the writing, not the subject. State the point directly."
|
||||
link: https://github.com/lancedb/docs/blob/main/STYLE.md#say-it-directly
|
||||
level: suggestion
|
||||
ignorecase: false
|
||||
scope: sentence
|
||||
tokens:
|
||||
# The page's role instead of its content, as in "This page is the concept".
|
||||
- '^[Tt]his page is the concept'
|
||||
# A filler sentence opener, listed in skills/docs-writer/SKILL.md.
|
||||
- '^That matters'
|
||||
tests:
|
||||
- name: flags a page describing its own role
|
||||
input: This page is the concept; the SQL reference is the specification.
|
||||
want: |
|
||||
1:1:LanceDB.VaguePhrases:'This page is the concept' talks about the writing, not the subject. State the point directly.
|
||||
- name: flags the filler opener
|
||||
input: That matters for partner workloads because names repeat.
|
||||
want: |
|
||||
1:1:LanceDB.VaguePhrases:'That matters' talks about the writing, not the subject. State the point directly.
|
||||
- name: leaves ordinary uses alone
|
||||
input: This page describes compaction. It is the operation that matters for video.
|
||||
want: ''
|
||||
- name: leaves specific descriptions and embedded phrases alone
|
||||
input: |
|
||||
This page is the entry point for the Python API. This page is the conceptual overview of the table model. The heading "That matters" is quoted here. Only the setting That matters is highlighted.
|
||||
want: ''
|
||||
- name: catches a filler opener after another sentence
|
||||
input: Names repeat. That matters for partner workloads.
|
||||
want: |
|
||||
1:15:LanceDB.VaguePhrases:'That matters' talks about the writing, not the subject. State the point directly.
|
||||
@@ -1,14 +1,13 @@
|
||||
name: Docs prose style
|
||||
|
||||
# Vale checks the mechanical rules in the LanceDB style guide
|
||||
# (lancedb/docs, STYLE.md) with the package pinned in .vale.ini. Its findings
|
||||
# are advisory annotations on the lines a pull request adds or changes and
|
||||
# never fail the job; an install, sync or configuration error still does.
|
||||
# Style findings are advisory; installation and configuration errors fail.
|
||||
on:
|
||||
pull_request:
|
||||
paths:
|
||||
- "docs/web/**/*.mdx"
|
||||
- ".vale.ini"
|
||||
- ".github/vale/**"
|
||||
- ".github/workflows/docs-style.yml"
|
||||
|
||||
permissions:
|
||||
contents: read
|
||||
@@ -40,6 +39,7 @@ jobs:
|
||||
uses: vale-cli/vale-action@518a9136acc6e6668ce7c00d367051e0941e87ff # v3.0.0
|
||||
with:
|
||||
version: none
|
||||
sync: false
|
||||
files: docs/web
|
||||
reporter: github-pr-annotations
|
||||
filter_mode: added
|
||||
|
||||
@@ -1,5 +1,6 @@
|
||||
# Prose style for the pages in docs/web: the shared LanceDB package, pinned by
|
||||
# release. The rules and guide live in lancedb/docs (STYLE.md and vale/).
|
||||
# Run `vale sync` once, then `vale docs/web/<page>.mdx`.
|
||||
StylesPath = .vale/styles
|
||||
Packages = https://github.com/lancedb/docs/releases/download/vale-lancedb-v0.1.0/LanceDB.zip
|
||||
StylesPath = .github/vale/styles
|
||||
MinAlertLevel = suggestion
|
||||
|
||||
[*.mdx]
|
||||
BasedOnStyles = LanceDB
|
||||
Vale.Repetition = warning
|
||||
|
||||
+4
-5
@@ -88,13 +88,12 @@ npm i -g mint # https://mintlify.com/docs/installation
|
||||
cd docs/web && mint dev
|
||||
```
|
||||
|
||||
Wording, names and punctuation follow the
|
||||
[LanceDB style guide](https://github.com/lancedb/docs/blob/main/STYLE.md).
|
||||
[Vale](https://vale.sh) checks part of it, and pull requests show its
|
||||
suggestions on the lines they change. To check a page yourself:
|
||||
[Vale](https://vale.sh) checks wording, names and punctuation using the
|
||||
[bundled LanceDB rules](.github/vale/README.md). Pull requests show suggestions
|
||||
on the lines they change. With Vale 3.24.0 installed, check a page with:
|
||||
|
||||
```bash
|
||||
vale sync && vale docs/web/indexing/vector-index.mdx
|
||||
vale docs/web/indexing/vector-index.mdx
|
||||
```
|
||||
|
||||
This repository holds a page at every path the site publishes, so the whole
|
||||
|
||||
Reference in New Issue
Block a user