Add 10 contributor onboarding playbooks by devang-ml · Pull Request #28737 · microsoft/onnxruntime

devang-ml · 2026-06-01T17:56:50Z

Summary

This PR adds a complete 10-playbook onboarding path for new ONNX Runtime contributors, moving from codebase orientation through advanced contribution workflows.

What is included

Adds and indexes ten contributor playbooks under docs/playbooks.
Establishes a suggested learning order in the plan document.
Provides practical, repo-grounded workflows for:
- architecture orientation
- local build/test/debug loops
- first PR flow
- session lifecycle tracing
- kernel contribution
- contrib operator contribution
- graph optimization/fusion work
- execution provider implementation
- memory/allocator/data movement debugging
- Python and C API binding extension

Files changed

docs/Contributor_Playbooks_Plan.md
docs/playbooks/01-repo-map-and-architecture-overview.md
docs/playbooks/02-build-test-and-debug-locally.md
docs/playbooks/03-first-pr-and-environment-setup.md
docs/playbooks/04-session-lifecycle-from-load-to-run.md
docs/playbooks/05-adding-or-changing-a-kernel.md
docs/playbooks/06-adding-a-contrib-operator.md
docs/playbooks/07-graph-optimizations-and-fusion-passes.md
docs/playbooks/08-execution-provider-implementation.md
docs/playbooks/09-memory-management-allocators-and-data-movement.md
docs/playbooks/10-python-and-c-api-binding-extension.md

Commit sequence

615a91b Add initial contributor playbooks
62dbdd2 Add session lifecycle playbook
dbd1764 Add kernel contribution playbook
d558e40 Add contrib operator playbook
727a35c Add graph optimization playbook
c42c3ae Add execution provider playbook
a783e14 Add memory and data movement playbook
7f72e42 Add Python and C API binding playbook

Validation

Documentation-only change.
Internal links and ordering were reviewed during authoring.

edgchen1 · 2026-06-01T20:56:55Z

+Windows example:
+
+```powershell
+cd build\Windows\RelWithDebInfo


on Windows, there's another <build config> directory when using the default Visual Studio generator

Suggested change

cd build\Windows\RelWithDebInfo

cd build\Windows\RelWithDebInfo\RelWithDebInfo

edgchen1 · 2026-06-01T21:00:25Z

+
+## Practical Debug Workflow
+
+1. Build in RelWithDebInfo while iterating.


Debug has the best debugging experience. RelWithDebInfo is useful if performance is important.

edgchen1 · 2026-06-02T22:42:49Z

+
+## Prerequisites
+
+- GitHub account and a fork of the ONNX Runtime repo


a fork is not strictly necessary for MS folks

edgchen1 · 2026-06-02T22:44:12Z

+## Prerequisites
+
+- GitHub account and a fork of the ONNX Runtime repo
+- C++ toolchain for your platform


also need CMake. it can be installed in the Python environment.

edgchen1 · 2026-06-02T22:47:12Z

+git checkout -b <short-feature-branch-name>
+```
+
+## Step 2: Create and activate a Python virtual environment


possibly worth mentioning Python virtual environment usage in the build/test/debug playbook. typically, you don't want to run the build script in the system python environment as it could install Python dependencies.

edgchen1 · 2026-06-02T23:27:49Z

+
+## Outcome
+
+By the end of this playbook, you will be able to add or modify a graph optimization pass, reason about where it runs in the optimizer pipeline, and validate correctness with targeted transformer tests.


reason about where it runs in the optimizer pipeline

should we describe the different optimization levels? or refer to the docs?
https://onnxruntime.ai/docs/performance/model-optimizations/graph-optimizations.html

edgchen1 · 2026-06-02T23:28:55Z

+
+By the end of this playbook, you will be able to start an execution provider implementation plan, choose between in-tree and plugin paths, and complete a minimal first-op bring-up with focused validation.
+
+This playbook uses [docs/ExecutionProvider_Playbook.md](../ExecutionProvider_Playbook.md) as the primary deep-dive source and adapts it into the contributor learning sequence.


is this file supposed to be added this PR?

edgchen1 · 2026-06-02T23:29:54Z

+
+## Outcome
+
+By the end of this playbook, you will be able to start an execution provider implementation plan, choose between in-tree and plugin paths, and complete a minimal first-op bring-up with focused validation.


choose between in-tree and plugin paths

the choice for a new EP should be an out-of-tree plugin EP.

edgchen1 · 2026-06-02T23:36:01Z

+
+## Outcome
+
+By the end of this playbook, you will be able to start an execution provider implementation plan, choose between in-tree and plugin paths, and complete a minimal first-op bring-up with focused validation.


the scope of this playbook (adding a new EP) seems very large in comparison to the others.

edgchen1 · 2026-06-02T23:40:01Z

@@ -0,0 +1,140 @@
+# Playbook 10: Python and C API Binding Extension


what about other languages? I think in terms of priority, the C++ API updates associated with a new C API are higher than the Python binding.

devang-ml added 8 commits June 1, 2026 16:57

Add initial contributor playbooks

615a91b

Add session lifecycle playbook

62dbdd2

Add kernel contribution playbook

dbd1764

Add contrib operator playbook

d558e40

Add graph optimization playbook

727a35c

Add execution provider playbook

c42c3ae

Add memory and data movement playbook

a783e14

Add Python and C API binding playbook

7f72e42

devang-ml marked this pull request as ready for review June 2, 2026 19:59

edgchen1 reviewed Jun 2, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add 10 contributor onboarding playbooks#28737

Add 10 contributor onboarding playbooks#28737
devang-ml wants to merge 8 commits into
mainfrom
dpatel/playbooks

devang-ml commented Jun 1, 2026

Uh oh!

edgchen1 Jun 1, 2026

Uh oh!

edgchen1 Jun 1, 2026

Uh oh!

edgchen1 Jun 2, 2026

Uh oh!

edgchen1 Jun 2, 2026

Uh oh!

edgchen1 Jun 2, 2026

Uh oh!

edgchen1 Jun 2, 2026

Uh oh!

edgchen1 Jun 2, 2026

Uh oh!

edgchen1 Jun 2, 2026

Uh oh!

edgchen1 Jun 2, 2026

Uh oh!

edgchen1 Jun 2, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

	cd build\Windows\RelWithDebInfo
	cd build\Windows\RelWithDebInfo\RelWithDebInfo


		## Practical Debug Workflow

		1. Build in RelWithDebInfo while iterating.


		## Prerequisites

		- GitHub account and a fork of the ONNX Runtime repo


		## Outcome

		By the end of this playbook, you will be able to add or modify a graph optimization pass, reason about where it runs in the optimizer pipeline, and validate correctness with targeted transformer tests.


		By the end of this playbook, you will be able to start an execution provider implementation plan, choose between in-tree and plugin paths, and complete a minimal first-op bring-up with focused validation.

		This playbook uses [docs/ExecutionProvider_Playbook.md](../ExecutionProvider_Playbook.md) as the primary deep-dive source and adapts it into the contributor learning sequence.

		@@ -0,0 +1,140 @@
		# Playbook 10: Python and C API Binding Extension

Conversation

devang-ml commented Jun 1, 2026

Summary

What is included

Files changed

Commit sequence

Validation

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants