new (style): Updated contributing docs and Vale for style guide assistance #16267

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open

sfanahata wants to merge 3 commits into master from style-guide-and-vale-linter

.github/styles/Sentry/Headings.yml

-Original file line number
+Diff line change
@@ -0,0 +1,31 @@
+    # Enforce Title Case for headings
+    extends: capitalization
+    message: "Use Title Case for headings: '%s'"
+    level: suggestion
+    scope: heading
+    match: $title
+    style: AP
+    # Allow certain words to be lowercase in titles
+    indicators:
+      - ":"
+    exceptions:
+      - a
+      - an
+      - and
+      - as
+      - at
+      - but
+      - by
+      - for
+      - in
+      - nor
+      - of
+      - on
+      - or
+      - so
+      - the
+      - to
+      - up
+      - yet
+      - vs
+      - via

.github/styles/Sentry/InclusiveLanguage.yml

-Original file line number
+Diff line change
@@ -0,0 +1,13 @@
+    # Sentry inclusive language rules
+    # See: https://develop.sentry.dev/getting-started/inclusive-language/
+    extends: substitution
+    message: "Use '%s' instead of '%s' for inclusive language."
+    level: warning
+    ignorecase: true
+    swap:
+      blacklist: blocklist
+      whitelist: allowlist
+      blacklisted: blocked
+      whitelisted: allowed
+      master/slave: primary/replica
+      grandfathered: legacy

.github/styles/Sentry/MarketingSpeak.yml

-Original file line number
+Diff line change
@@ -0,0 +1,36 @@
+    # Avoid corporate marketing language
+    extends: existence
+    message: "Avoid marketing speak: '%s'. Be direct and specific instead."
+    level: suggestion
+    ignorecase: true
+    tokens:
+      - best-in-class
+      - best in class
+      - world-class
+      - world class
+      - cutting-edge
+      - cutting edge
+      - industry-leading
+      - industry leading
+      - leverage
+      - leveraging
+      - leverages
+      - synergy
+      - synergies
+      - synergize
+      - paradigm
+      - paradigm shift
+      - game-changer
+      - game changer
+      - revolutionary
+      - revolutionize
+      - disruptive
+      - next-generation
+      - next generation
+      - bleeding-edge
+      - bleeding edge
+      - robust solution
+      - seamlessly
+      - empower
+      - empowers
+      - empowering

.github/styles/Sentry/ProductNames.yml

-Original file line number
+Diff line change
@@ -0,0 +1,15 @@
+    # Ensure proper capitalization of Sentry product names
+    extends: substitution
+    message: "Use '%s' instead of '%s' for proper capitalization."
+    level: warning
+    ignorecase: false
+    swap:
+      '(?<![A-Za-z])sentry(?![A-Za-z-])': Sentry
+      'Sentry sdk': Sentry SDK
+      'sentry SDK': Sentry SDK
+      'sentry sdk': Sentry SDK
+      '(?<![A-Za-z])dsn(?![A-Za-z])': DSN
+      javascript: JavaScript
+      Javascript: JavaScript
+      typescript: TypeScript
+      Typescript: TypeScript

.github/styles/Sentry/SentenceLength.yml

-Original file line number
+Diff line change
@@ -0,0 +1,8 @@
+    # Flag overly long sentences
+    extends: occurrence
+    message: "This sentence has %s words. Consider breaking it into shorter sentences (aim for under 25 words)."
+    level: suggestion
+    # Count words in a sentence
+    scope: sentence
+    max: 35
+    token: '\b\w+\b'

.github/styles/Sentry/Wordiness.yml

-Original file line number
+Diff line change
@@ -0,0 +1,21 @@
+    # Prefer simpler words and phrases
+    extends: substitution
+    message: "Consider using '%s' instead of '%s' for clarity."
+    level: suggestion
+    ignorecase: true
+    swap:
+      in order to: to
+      utilize: use
+      utilizes: uses
+      utilizing: using
+      prior to: before
+      subsequent to: after
+      in the event that: if
+      at this point in time: now
+      due to the fact that: because
+      for the purpose of: to
+      in close proximity to: near
+      a large number of: many
+      the majority of: most
+      in spite of the fact that: although
+      click on: click

.github/styles/config/vocabularies/Sentry/accept.txt

-Original file line number
+Diff line change
@@ -0,0 +1,107 @@
+    # Sentry-specific terms that should be accepted
+    # One term per line
+    # Product names
+    Sentry
+    DSN
+    SDK
+    SDKs
+    API
+    APIs
+    CLI
+    MCP
+    # Technical terms
+    sourcemap
+    sourcemaps
+    webpack
+    Webpack
+    rollup
+    Rollup
+    esbuild
+    Vite
+    npm
+    yarn
+    pnpm
+    Bun
+    Node\.js
+    TypeScript
+    JavaScript
+    React
+    Vue
+    Angular
+    Next\.js
+    Nuxt
+    Svelte
+    SvelteKit
+    Remix
+    Astro
+    Gatsby
+    Django
+    Flask
+    FastAPI
+    Rails
+    Laravel
+    Spring
+    Express
+    Koa
+    Fastify
+    Deno
+    # Sentry features
+    breadcrumb
+    breadcrumbs
+    stacktrace
+    stacktraces
+    minidump
+    minidumps
+    symbolication
+    proguard
+    ProGuard
+    dSYM
+    dSYMs
+    # Common abbreviations
+    HTTP
+    HTTPS
+    URL
+    URLs
+    JSON
+    YAML
+    TOML
+    UUID
+    UUIDs
+    OAuth
+    SSO
+    SAML
+    JWT
+    JWTs
+    CORS
+    CDN
+    CI
+    CD
+    # Tracing terms
+    span
+    spans
+    transaction
+    transactions
+    trace
+    traces
+    traceId
+    spanId
+    # Error monitoring terms
+    grouping
+    fingerprint
+    fingerprints
+    unhandled
+    handled
+    # Performance terms
+    LCP
+    FCP
+    TTFB
+    CLS
+    FID
+    INP

.github/styles/config/vocabularies/Sentry/reject.txt

-Original file line number
+Diff line change
@@ -0,0 +1,5 @@
+    # Terms that should always be flagged
+    # One term per line
+    # Inclusive language violations are handled by InclusiveLanguage.yml
+    # This file is for additional rejections if needed

.gitignore

            
                      Original file line number
                      Diff line number
                      Diff line change
                  
    @@ -109,5 +109,5 @@ yalc.lock
  
    /public/doctree.json

    /public/doctree-dev.json

    # Claude Code local files

    .claude/settings.local.json
      
    # Vale synced packages (downloaded via `vale sync`)

    .github/styles/write-good/

.vale.ini

-Original file line number
+Diff line change
@@ -0,0 +1,33 @@
+    # Vale configuration for Sentry documentation
+    # This is an advisory linter - suggestions only, not enforced in CI
+    # See: https://vale.sh/docs/
+    StylesPath = .github/styles
+    MinAlertLevel = suggestion
+    # Use Sentry vocabulary for accepted technical terms
+    Vocab = Sentry
+    # Packages to download (run `vale sync` to install)
+    Packages = write-good
+    # Treat MDX files as Markdown (avoids need for mdx2vast parser)
+    [formats]
+    mdx = md
+    # Process markdown and MDX files in docs directories
+    [docs/**/*.{md,mdx}]
+    BasedOnStyles = Sentry, write-good
+    [develop-docs/**/*.{md,mdx}]
+    BasedOnStyles = Sentry, write-good
+    [includes/**/*.{md,mdx}]
+    BasedOnStyles = Sentry, write-good
+    [platform-includes/**/*.{md,mdx}]
+    BasedOnStyles = Sentry, write-good
+    # Ignore code blocks and inline code
+    TokenIgnores = (\x60[^\x60]+\x60)
+    BlockIgnores = (?s)(\x60{3}.*?\x60{3})

AGENTS.md

-Original file line number
+Diff line change
@@ Expand Up @@
     | `yarn lint:eslint` | ESLint check |
     | `yarn lint:prettier` | Prettier check |
+    ## Documentation Writing Style
+    When writing or editing documentation content in `docs/`:
+    ### Tone & Voice
+    - **Supportive Peer:** Write like a developer talking to another developer. Use "we" to include both author and reader.
+    - **Direct & Honest:** Avoid corporate fluff ("best-in-class", "leverage", "synergy"). If something is a workaround, call it that.
+    - **Inclusive:** Use gender-neutral language. Use "they/them" for the reader.
+    ### Stylistic Rules
+    - **American English:** Use U.S. spelling (color, organize, center).
+    - **Scannability:** Short paragraphs (2-3 sentences max). Use bullet points for lists.
+    - **Active Voice:** "Sentry groups similar errors" not "Similar errors are grouped by Sentry."
+    - **Headings:** Use Title Case for all heading levels. Never stack headlines without body text between them.
+    ### Formatting
+    - **Code First:** Show code examples, then explain them.
+    - **Bold for Emphasis:** Use **bold** for UI elements and key actions.
+    - **UI References:** Click **Save Changes**, go to **Settings > Projects**.
+    ### Word Choice
+    - Use "blocklist/allowlist" not "blacklist/whitelist"
+    - Use "master/secondary", "primary/secondary" not "master/slave"
+    - Use "to" not "in order to"
+    - Use "use" not "utilize"
+    - Verb forms: "set up" (verb) vs "setup" (noun), "log in" vs "login"
+    For the complete style guide, see: https://docs.sentry.io/contributing/approach/style-guide/
     ## Developer Documentation (develop-docs/)
     When writing requirements in `develop-docs/`:
@@ Expand Down @@

docs/contributing/approach/index.mdx

-Original file line number
+Diff line change
@@ Expand Up / @@ -34,6 +34,8 @@ Keep these concepts in mind when contributing to docs: @@
 . Technical accuracy is our primary consideration. Our content helps every developer diagnose, fix, and optimize their code.
 . Use inclusive language, which we discuss more fully [here](https://develop.sentry.dev/getting-started/inclusive-language/).
-. Feedback is a gift - share your PR so we can improve our content.
+. Follow our [Style Guide](/contributing/approach/style-guide/) for tone, voice, and formatting standards.
+. For larger documentation updates, use the docs-review agent skill in Cursor or refer to the `AGENTS.md` file for AI assistant guidance on maintaining Sentry's voice and style.
+. Feedback is a gift - share your PR so we can improve our content.
     <PageGrid />

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

new (style): Updated contributing docs and Vale for style guide assistance #16267

Uh oh!

Diff view

Diff view

There are no files selected for viewing

Uh oh!

Uh oh!

Uh oh!

new (style): Updated contributing docs and Vale for style guide assistance #16267

Are you sure you want to change the base?

Uh oh!

new (style): Updated contributing docs and Vale for style guide assistance #16267

Uh oh!

Uh oh!

Diff view

Diff view

There are no files selected for viewing

Uh oh!

Uh oh!