Skip to content

Contributing to Jupyter Notebook Validator Operator

Thank you for your interest in contributing! This guide covers everything you need to get started.

Who Is This For?

This project serves two audiences. Pick the path that matches your role:

Data Scientists and Notebook Authors

You want to validate notebooks before they reach production. You do not need Go, Operator SDK, or a local cluster.

  1. Try it locally first with Validate a notebook locally. Run a notebook through Papermill inside Podman or Docker on your laptop. No cluster needed.
  2. Submit to a cluster when ready. Install the operator via OperatorHub or Helm: 
    helm repo add jupyter-validator https://tosin2013.github.io/jupyter-notebook-validator-operator
helm install jupyter-validator jupyter-validator/jupyter-notebook-validator-operator \
  --namespace jupyter-validator-system --create-namespace
  3. Submit a validation job by copying a sample CR from config/samples/: 
    kubectl apply -f config/samples/mlops_v1alpha1_notebookvalidationjob.yaml
  4. Check status: 
    kubectl get notebookvalidationjobs
kubectl describe notebookvalidationjob <name>

See Quick Start CI/CD for the full cluster setup.

Operator / Platform Contributors

You want to change the operator code, fix bugs, or add features. Continue reading below for the full development setup.

Local cluster for testing: Kind is the recommended local cluster. It matches the E2E CI environment and runs on any Linux or macOS host.

OpenShift Local (CRC) is not a supported onboarding path. CRC's first-party docs cover RHEL and Fedora only; Ubuntu (this project's primary development host) is not supported. CRC also requires a Red Hat pull secret and significant RAM. If you already run CRC on a supported host, you may point oc at it, but the project does not document or test that workflow.

Table of Contents

Code of Conduct

This project follows the Contributor Covenant Code of Conduct. By participating, you are expected to uphold this code.

Getting Started

Prerequisites

  • Go 1.22+ (install guide)
  • Docker or Podman (for building container images)
  • kubectl or oc CLI
  • make
  • Kind (recommended for local integration/E2E testing; install guide)

Fork and Clone

  1. Fork the repository on GitHub.
  2. Clone your fork locally:
git clone https://github.com/<your-username>/jupyter-notebook-validator-operator.git
cd jupyter-notebook-validator-operator
  1. Add the upstream remote:
git remote add upstream https://github.com/tosin2013/jupyter-notebook-validator-operator.git

Development Environment

Build the Operator

make build

Run Tests

# Unit and integration tests
make test

# End-to-end tests (requires a running cluster)
make test-e2e

Code Quality

Run all of the following before submitting a PR:

make fmt       # Format code
make vet       # Go static analysis
make lint      # Linter (golangci-lint)
make lint-fix  # Auto-fix linting issues

The linter config (.golangci.yml) uses golangci-lint v2 schema. Do not add linters under the removed v1 keys (linters-settings, issues.exclude-rules, disable-all).

Regenerate CRDs and DeepCopy

If you modify API types in api/v1alpha1/, regenerate the manifests:

make manifests generate

Run Locally

# Install CRDs into your cluster
make install

# Run the operator against the cluster
make run

Making Changes

Branch Naming

Create a descriptive branch from main:

feature/short-description
fix/issue-number-description
docs/what-changed

Commit Messages

Write clear, concise commit messages:

  • Use the imperative mood ("Add feature" not "Added feature")
  • Reference related issues when applicable (e.g., Fixes #42)
  • Keep the subject line under 72 characters

Architectural decisions

Do not edit an Accepted ADR in place to change the decision. Follow Changing ADRs in docs/adrs/README.md: run Repo Governor completion.py on the issue first, draft a Proposed superseding ADR, and leave Accepted / Superseded status for human ratification.

Code Style

  • Follow standard Go conventions and idioms.
  • All exported types and functions must have doc comments.
  • Keep functions focused and testable.
  • Add tests for new functionality.

Submitting a Pull Request

  1. Ensure your branch is up to date with main:
git fetch upstream
git rebase upstream/main
  1. Verify that all checks pass locally:
make fmt vet lint test

  1. Push your branch and open a PR against main.

  2. In your PR description, include:

  3. A summary of what changed and why.
  4. The type of change (bug fix, feature, refactor, docs).
  5. How you tested the changes.

  6. Any related issue numbers.

  7. A maintainer will review your PR. Please be responsive to feedback.

Reporting Issues

Include as much detail as possible: operator version, Kubernetes/OpenShift version, logs, and steps to reproduce.

Community

For general questions, usage tips, and ideas that are not a bug or a tracked feature request, use GitHub Discussions.

Maintainer note: GitHub “About” metadata

To sync the repository description, homepage URL, topics, and Discussions flag via the GitHub CLI (after gh auth login):

./scripts/update-github-repo-metadata.sh

Specialized Contributions

Adding Model Serving Platforms

The operator supports a plugin-based architecture for model serving platforms. For detailed instructions on adding support for new platforms (e.g., custom inference servers), see the Contributing Model Platforms Guide.

Helm Chart

Changes to the Helm chart in helm/ should be validated with:

make helm-lint
make helm-template

License

By contributing, you agree that your contributions will be licensed under the Apache License 2.0.