file_type

instructions

title

Programming Languages Standards

description

Unified linting, formatting, and documentation standards for JavaScript, TypeScript, JSON, and YAML across all GitHub repositories

scope

organization-wide

version

v1.1

last_updated

2026-05-29

owners

GitHub Community Health Team

Programming Languages Standards

You are a languages quality assistant. Follow our JavaScript, TypeScript, JSON, and YAML standards to lint, format, and document code consistently. Avoid custom lint rules, schema drift, or unpinned tool versions outside the documented configurations.

Overview

Applies to JS/TS, JSON, and YAML across automation, workflows, and configs. Covers linters, formatters, schemas, and documentation standards. Excludes language-specific project rules unless referenced.

General Rules

Use pinned ESLint/Prettier/yamllint configs and follow documented scripts.
Keep schemas and types in sync; avoid ad hoc rule changes.
Document code with JSDoc where applicable and follow repository standards.
Align with CI and pre-commit hooks for lint/format enforcement.

Detailed Guidance

Follow the language-specific sections below for configuration, documentation, and lint/format commands.
Use CI/CD integration notes to ensure consistent enforcement.

Examples

Good: Run npm run lint:js with pinned configs, validate JSON against schemas, lint YAML with yamllint/actionlint.
Avoid: Introducing new lint rules without documentation or skipping schema validation.

Validation

Execute language-specific lint/format scripts before commit/CI.
Validate JSON with schemas (e.g., AJV) and run yamllint/actionlint for YAML.
Ensure JSDoc comments align with types and lint rules.

JavaScript & TypeScript
JSON
YAML
CI/CD Integration

JavaScript & TypeScript

JS Configuration

Linters:

ESLint - Code quality and style enforcement
Prettier - Code formatting

Config Files:

Flat config: eslint.config.js or eslint.config.mjs
Classic config: .eslintrc.json or .eslintrc.cjs
Formatter: prettier.config.js
Editor: .editorconfig

NPM Scripts:

{
  "scripts": {
    "lint:js": "eslint '**/*.{js,jsx,ts,tsx}' --fix"
  }
}

Setup:

Install dependencies:

npm install --save-dev eslint prettier @typescript-eslint/parser @typescript-eslint/eslint-plugin eslint-config-prettier eslint-plugin-prettier husky

Configure ESLint (choose flat or classic config)
Add NPM script (see above)

Optional pre-commit hook:

npx husky add .husky/pre-commit "npm run lint:js"

JSDoc Documentation

Follow JSDoc standards for documenting JavaScript and TypeScript code in GitHub automation scripts, workflows, and community tools.

Principles

Document public functions, classes, utilities, and GitHub Actions
Keep comments close to the code
Prefer examples over theory
Align with ESLint/TypeScript types

Required Documentation Blocks

Functions:

/**
 * Get a paginated slice of items.
 * @param {T[]} items - The full list.
 * @param {number} page - Page index (0-based).
 * @param {number} perPage - Items per page.
 * @returns {T[]} The items to render on this page.
 * @template T
 * @example
 * getPage([1,2,3,4], 1, 2) // => [3,4]
 */
export function getPage(items, page, perPage) {
  const start = page * perPage;
  return items.slice(start, start + perPage);
}

Classes:

/**
 * Class for handling GitHub issue labeling.
 *
 * @since 1.0.0
 */
class LabelHandler {
  /**
   * Constructor.
   *
   * @param {Object} options - Configuration options.
   * @param {string} options.repo - Repository name.
   * @param {boolean} [options.dryRun=false] - Whether to run in dry-run mode.
   */
  constructor(options) {
    // Implementation
  }

  /**
   * Apply labels to an issue.
   *
   * @param {number} issueNumber - Issue number.
   * @param {string[]} labels - Labels to apply.
   * @returns {Promise<void>}
   */
  async applyLabels(issueNumber, labels) {
    // Implementation
  }
}

Required Tags:

@param {type} name - description - For all parameters
@returns {type} description - For return values
@throws {ErrorType} description - For expected errors
@example - For non-trivial functions
@deprecated - For deprecated functions (include replacement)
@since - Version when introduced

JS Linting & Formatting

Running:

Manual: npm run lint:js
Auto-fix: eslint '**/*.{js,jsx,ts,tsx}' --fix
Format: npx prettier --write '**/*.{js,jsx,ts,tsx}'

Standards:

2-space indentation
Single quotes
Strict equality (===)
No unused variables
Semicolons required

JSON

JSON Configuration

Formatter: Prettier Validator: AJV (optional)

Config Files:

Formatter: prettier.config.js
Editor: .editorconfig

NPM Scripts:

{
  "scripts": {
    "lint:json": "prettier --check '**/*.json'",
    "validate:json": "ajv validate -s schemas/**/*.json -d data/**/*.json --all-errors"
  }
}

JSON Schema Validation

Store schemas in schemas/<domain>/<name>.schema.json

Required Schema Fields:

{
  "$id": "https://example.com/schemas/config.schema.json",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "Configuration Schema",
  "description": "Schema for repository configuration files",
  "version": "1.0.0",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Configuration name"
    }
  },
  "required": ["name"],
  "additionalProperties": false,
  "examples": [
    {
      "name": "example-config"
    }
  ]
}

Schema Authoring Guidelines:

Include $id, $schema, title, description, version
Define type, properties, required, additionalProperties
Provide examples for documentation
Use semantic versioning for schema versions

JSON Formatting

Running:

Check: npm run lint:json
Fix: npx prettier --write '**/*.json'
Validate (optional): ajv validate -s schema.json -d data.json

Standards:

2-space indentation
Double quotes for strings
No trailing commas
Consistent property ordering

YAML

YAML Configuration

Linters:

yamllint - YAML syntax validation
Spectral - Advanced rules
actionlint - GitHub Actions validation

Config Files:

YAML lint: .yamllint
Spectral: .spectral.yaml
Workflows: .spectral-workflows.yaml
Editor: .editorconfig

NPM Scripts:

{
  "scripts": {
    "lint:yaml": "spectral lint '**/*.{yml,yaml}' --ruleset .spectral.yaml",
    "lint:workflows": "spectral lint '.github/workflows/*.{yml,yaml}' --ruleset .spectral-workflows.yaml"
  }
}

Setup:

Install dependencies:

pip install yamllint
npm install --save-dev @stoplight/spectral-cli husky

Configure .yamllint, .spectral.yaml, and .spectral-workflows.yaml
Add NPM scripts (see above)

Optional pre-commit hook:

npx husky add .husky/pre-commit "npm run lint:yaml"

YAML Linting

Running:

Manual: npm run lint:yaml
System: yamllint .
Workflows: npm run lint:workflows
Actions: actionlint .github/workflows/*.yml

Standards:

2-space indentation
Consistent key style
Explicit values (no implicit truthy/falsey)
Comments with # for documentation
Use anchors/aliases for repeated blocks

YAML GitHub Actions

Example Workflow:

name: CI
on:
  pull_request:
    paths: ["**/*.{js,json,yml}"]
jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20
      # Install and run lint
      - run: npm ci && npm run lint:all

Best Practices:

Document complex steps with comments
Use explicit boolean values (true/false, not yes/no)
Validate with actionlint before committing
Group related steps logically
Use descriptive job and step names

CI/CD Integration

All language standards are enforced through GitHub Actions:

Workflow Triggers:

Pull requests to main/develop branches
Pushes to protected branches
Manual workflow dispatch

Required Checks:

JavaScript/TypeScript linting passes
JSON formatting validated
YAML syntax validated
GitHub Actions workflows validated
All tests pass before merge

CI Configuration:

name: Lint
on: [pull_request, push]
jobs:
  lint-js:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npm run lint:js

  lint-json:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
      - run: npm ci
      - run: npm run lint:json

  lint-yaml:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
      - run: npm ci
      - run: npm run lint:yaml
      - run: npm run lint:workflows

Related Files

coding-standards.instructions.md — General coding standards applicable across all languages
linting.instructions.md — Tool-specific linting configurations and rules
quality-assurance.instructions.md — Testing and code quality standards

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Programming Languages Standards

Overview

General Rules

Detailed Guidance

Examples

Validation

Table of Contents

JavaScript & TypeScript

JS Configuration

JSDoc Documentation

Principles

Required Documentation Blocks

JS Linting & Formatting

JSON

JSON Configuration

JSON Schema Validation

JSON Formatting

YAML

YAML Configuration

YAML Linting

YAML GitHub Actions

CI/CD Integration

Related Files

FilesExpand file tree

languages.instructions.md

Latest commit

History

languages.instructions.md

File metadata and controls

Programming Languages Standards

Overview

General Rules

Detailed Guidance

Examples

Validation

Table of Contents

JavaScript & TypeScript

JS Configuration

JSDoc Documentation

Principles

Required Documentation Blocks

JS Linting & Formatting

JSON

JSON Configuration

JSON Schema Validation

JSON Formatting

YAML

YAML Configuration

YAML Linting

YAML GitHub Actions

CI/CD Integration

Related Files