Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
138 lines (93 loc) · 3.83 KB

CONTRIBUTING.md

File metadata and controls

138 lines (93 loc) · 3.83 KB
Raw

Contributing to Red Hat AI Examples

This guide will help you set up your development environment and understand the code quality standards.

Development Setup

This repository uses automated code quality and security scanning tools. To contribute, you'll need to install the following development tools:

Required Tools

Python Tools:

pip install pre-commit ruff detect-secrets

  • pre-commit - Manages git hooks for automated code quality checks

  • ruff - Fast Python linter and formatter

  • detect-secrets - Prevents secrets from being committed to the repository

  • markdownlint-cli (requires Node.js):

    npm install -g markdownlint-cli

  • gitleaks (for local secret scanning):

Setting Up Pre-commit Hooks

After installing the tools, set up the pre-commit hooks:

# Install git hooks
pre-commit install
pre-commit install --hook-type commit-msg

# To Run hooks on all files
pre-commit run --all-files

The pre-commit hooks will automatically run on every commit to check:

  • Python code quality and formatting (Ruff)
  • Markdown linting
  • Secret scanning (Gitleaks, Talisman, and detect-secrets)
  • General file quality (trailing whitespace, YAML syntax, etc.)

See .pre-commit-config.yaml for the complete configuration.

Working with Secret Scanning

If detect-secrets fails during commit, it means potential secrets were detected in your changes.

If detect-secrets flags something that is not actually a secret (false positive), you have to:

Update the baseline (recommended for legitimate false positives):

# Scan and update the baseline
detect-secrets scan > .secrets.baseline

# Audit the baseline to mark false positives
detect-secrets audit .secrets.baseline

# Commit the updated baseline
git add .secrets.baseline
git commit -m "Update detect-secrets baseline"

Manual Code Quality Checks

You can also run these tools manually:

# Python linting
ruff check .

# Fix Python linting
ruff check --fix .

# Python formatting
ruff format .

# Markdown linting
markdownlint .

# Fix Markdown lint
markdownlint --fix .

# Run all pre-commit hooks
pre-commit run --all-files

Working with Jupyter Notebooks

This repository uses nbstripout (via pre-commit) to automatically strip outputs and some metadata from Jupyter notebooks before they are committed. This keeps diffs small and avoids committing large or transient outputs.

Preserving Specific Cell Outputs

In some cases, you may need to keep the output of a particular cell (for example, a reference plot or a summary table that is important for readers). To exclude a cell's output from being stripped by nbstripout, mark the cell with special metadata:

  • Using a cell tag (recommended)

    • Select the cell
    • In the right sidebar, open the Tags panel
    • Add the tag keep_output

  • Using cell metadata directly

    • Open the cell metadata editor and add:

      {
  "keep_output": true
}

Cells tagged with keep_output (or with metadata "keep_output": true) will keep their outputs even when the nbstripout pre-commit hook runs. All other cells will have their outputs stripped as usual.

Code Quality Standards

All contributions must pass the automated code quality checks before being merged. This includes:

  • Python code must be formatted with Ruff
  • Python code must pass Ruff linting checks
  • Markdown files must follow markdownlint rules
  • No secrets or sensitive information should be committed
  • No trailing whitespace or other common file issues

Submitting Changes

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Ensure all pre-commit hooks pass
  5. Submit a pull request