docs: improve the contributor experience of CONTRIBUTING.md (#5507)

Signed-off-by: Dan Gil <dagil@nvidia.com>

.github/ISSUE_TEMPLATE/config.yml

@@ -4,5 +4,5 @@ contact_links:
     url: https://www.nvidia.com/en-us/ai/dynamo/
     about: Refer to the Dynamo documentation to help you get started.
   - name: Dynamo Community Support
-    url: https://discord.gg/dynamo
+    url: https://discord.gg/nvidia-dynamo
     about: Refer to the Dynamo Discord server for community support.

CONTRIBUTING.md

@@ -15,238 +15,277 @@ See the License for the specific language governing permissions and
 limitations under the License.
 -->
 
-# Contribution Guidelines
+# Contributing to Dynamo
 
-## External Contributors: Issue-First Workflow
+Thank you for your interest in contributing to Dynamo! Whether you're fixing a typo, reporting a bug, improving documentation, or building a new feature—every contribution matters and helps make Dynamo better for everyone.
 
-Thank you for your interest in contributing to Dynamo. To help us review your work efficiently, please follow the workflow below.
+This guide will help you get started. If you have questions, join us on [Discord](https://discord.gg/nvidia-dynamo) or open a [GitHub Discussion](https://github.com/ai-dynamo/dynamo/discussions).
 
-### When Is a GitHub Issue Required?
+**TL;DR for experienced contributors:**
 
-**You can submit a PR directly without an issue if:**
+1. Fork and clone the repo
+2. Create a branch: `git checkout -b yourname/fix-description`
+3. Make changes, run `pre-commit`
+4. Commit with DCO sign-off: `git commit -s -m "fix: description"`
+5. Open a PR targeting `main`
 
-- Your change is **<100 lines of code** AND addresses a simple, focused concern (typos, simple bug fixes, formatting)
-- **OR** your PR addresses an **existing approved GitHub Issue** (link with "Fixes #123")
+## New to Dynamo?
 
-**You must create a GitHub Issue first for:**
+If this is your first contribution, here's the recommended path:
 
-- Changes ≥100 lines of code
-- New features, architecture changes, or multi-component changes
-- Any change that requires design discussion
+1. **Set up** your development environment using the [Developing Locally](README.md#developing-locally) guide
+2. **Find an issue** — Browse [open issues](https://github.com/ai-dynamo/dynamo/issues) or look for:
+
+   | Issue Type | Description |
+   |------------|-------------|
+   | [Good first issues](https://github.com/ai-dynamo/dynamo/labels/good-first-issue) | Beginner-friendly |
+   | [Help wanted](https://github.com/ai-dynamo/dynamo/labels/help-wanted) | Community contributions welcome |
 
-**Note**: All PRs are triaged. If your PR lacks sufficient context or understanding, reviewers will reject the PR and ask you to first submit an issue and get approval before proceeding.
+3. **Start small** — Documentation fixes, bug fixes, and test improvements are great first contributions
+4. **Ask questions** — Join [Discord](https://discord.gg/nvidia-dynamo) or open a [Discussion](https://github.com/ai-dynamo/dynamo/discussions) if you get stuck
 
-### Issue-First Workflow Steps
+**Community Impact:** 70+ external contributors have merged PRs, with 130+ community contributions since launch and ~8 new contributors joining each month. Your contribution matters—[see our contributors](https://github.com/ai-dynamo/dynamo/graphs/contributors).
 
-**If you are an external contributor and your change requires a GitHub Issue**, please follow this workflow. This process ensures that external contributions are well-aligned with the project's goals and reduces the likelihood of significant rework.
+## Code of Conduct
 
-1. **Create a GitHub Issue First** – Before writing any code, [open a GitHub Issue](https://github.com/ai-dynamo/dynamo/issues/new?template=contribution_request.yml) using the **Contribution Request** template.
+We are committed to providing a welcoming and inclusive environment. Please read and follow our [Code of Conduct](CODE_OF_CONDUCT.md).
 
-2. **Identify the Problem** – Clearly explain the problem you are trying to solve, including any relevant context, error messages, or use cases.
+---
+
+## Ways to Contribute
 
-3. **Recommend a Solution** – Propose your intended solution or approach in the issue. Include:
-   - **Estimated PR size**: XS / S / M / L / XL / XXL (use your best judgment)
-   - **Files affected**: Approximate number and which components/interfaces
-   - **Type of change**:
-     - **Bug fix**: Corrects existing behavior with minimal code changes; should include tests that capture the issue
-     - **New feature**: Adds new behavior or capability; requires comprehensive tests for the new functionality
-     - **Refactoring**: Restructures code without changing behavior; no new tests required
-     - **Performance improvement**: Optimizes existing behavior; should include before/after benchmarks
+### Report a Bug
 
-   This helps the Dynamo team understand your plan, assess complexity, and provide early feedback. PRs that significantly exceed their stated size may be rejected.
+Found something broken? [Open a bug report](https://github.com/ai-dynamo/dynamo/issues/new?template=bug_report.yml) with:
+- Steps to reproduce
+- Expected vs. actual behavior
+- Environment details (OS, GPU, Python version, Dynamo version)
 
-4. **Get Approval** – Wait for the Dynamo team to review and approve both the problem statement and your proposed solution. This ensures alignment with the project's architecture and roadmap before you invest time in implementation. Once approved, a maintainer will apply the `approved-for-pr` label to your issue.
+### Improve Documentation
 
-5. **Submit a Pull Request** – Once your issue has the `approved-for-pr` label, [submit a PR](https://github.com/ai-dynamo/dynamo/compare) that references the issue. Link your PR to the issue using [GitHub keywords](https://docs.github.com/en/issues/tracking-your-work-with-issues/using-issues/linking-a-pull-request-to-an-issue) (e.g., "Fixes #123" or "Closes #123").
+Documentation improvements are always welcome. This includes:
+- Fixing typos or unclear explanations
+- Adding examples or tutorials
+- Improving API documentation
 
-6. **Address Code Rabbit Review** – Wait for the automated Code Rabbit review to complete. Address its suggestions, including the nitpicks—they are often quite insightful and help improve code quality.
+Small doc fixes can be submitted directly as PRs without an issue.
 
-7. **Ensure CI Tests Pass** – Wait for all CI tests to pass. If any tests fail, investigate and fix the issues before requesting human review.
+### Propose a Feature
 
-8. **Check CODEOWNERS** – Review the [CODEOWNERS](https://github.com/ai-dynamo/dynamo/blob/main/CODEOWNERS) file to identify which team members need to sign off on your PR based on the files you've modified.
+Have an idea for a new feature? [Open a feature request](https://github.com/ai-dynamo/dynamo/issues/new?template=feature_request.yml) to discuss it with Dynamo maintainers before implementation.
 
-9. **Request a Review** – Add whomever approved your GitHub Issue as a reviewer on your PR. Please also add [@dagil-nvidia](https://github.com/dagil-nvidia) for visibility.
+### Contribute Code
 
-> **Note on AI-Generated Code**: While Dynamo encourages the use of AI-generated code, it is the full responsibility of the submitter to understand every change in the PR. Failure to demonstrate sufficient understanding of the submitted code will result in rejection.
+Ready to write code? See the [Contribution Workflow](#contribution-workflow) section below for the process.
 
 ---
 
-## General Contribution Guidelines
+## What Happens to Your Issue
 
-Contributions that fix documentation errors or that make small changes
-to existing code can be contributed directly by following the rules
-below and submitting an appropriate PR.
+### Priority Levels
 
-Contributions intended to add significant new functionality must
-follow a more collaborative path described in the following
-points. Before submitting a large PR that adds a major enhancement or
-extension, be sure to submit a GitHub issue that describes the
-proposed change so that the Dynamo team can provide feedback.
+When triaged, issues are assigned a priority based on impact:
 
-- As part of the GitHub issue discussion, a design for your change
-  will be agreed upon. An up-front design discussion is required to
-  ensure that your enhancement is done in a manner that is consistent
-  with Dynamo's overall architecture.
+| Priority | Meaning |
+|----------|---------|
+| **Urgent** | Critical blocker—system failure, security vulnerability, data loss |
+| **P0** | High impact—major functionality broken, blocking multiple users |
+| **P1** | Medium impact—workarounds exist, or popular feature request |
+| **P2** | Low impact—minor bugs, nice-to-have features, cosmetic issues |
 
-- The Dynamo project is spread across multiple GitHub Repositories.
-  The Dynamo team will provide guidance about how and where your enhancement
-  should be implemented.
+### Status Labels
 
-- Testing is a critical part of any Dynamo
-  enhancement. You should plan on spending significant time on
-  creating tests for your change. The Dynamo team will help you to
-  design your testing so that it is compatible with existing testing
-  infrastructure.
+| Status | What It Means |
+|--------|---------------|
+| `needs-triage` | We're reviewing your issue |
+| `needs-info` | We need more details from you |
+| `approved-for-pr` | Ready for implementation—submit a PR |
+| `in-progress` | Someone is working on this |
+| `blocked` | Waiting on external dependency |
 
-- If your enhancement provides a user visible feature then you need to
-  provide documentation.
+### Response Expectations
 
-# Contribution Rules
+We aim to:
+- **Respond** to new issues within a few business days
+- **Triage** high-priority issues (P0/P1) within a week
 
-- The code style convention is enforced by common formatting tools
-  for a given language (such as clang-format for c++, black for python).
-  See below on how to ensure your contributions conform. In general please follow
-  the existing conventions in the relevant file, submodule, module,
-  and project when you add new code or when you extend/fix existing
-  functionality.
+Issues with no activity for 30 days may be auto-closed (can be reopened).
 
-- Avoid introducing unnecessary complexity into existing code so that
-  maintainability and readability are preserved.
+### Good First Issues
 
-- Try to keep code changes for each pull request (PR) as concise as possible:
+Issues labeled `good-first-issue` are sized for new contributors. We provide extra guidance on these—look for clear acceptance criteria and a suggested approach in the issue description.
 
-  - Fillout PR template with clear description and mark applicable checkboxes
+---
 
-  - Avoid committing commented-out code.
+## Quick Start for Contributors
 
-  - Wherever possible, each PR should address a single concern. If
-    there are several otherwise-unrelated things that should be fixed
-    to reach a desired endpoint, it is perfectly fine to open several
-    PRs and state in the description which PR depends on another
-    PR. The more complex the changes are in a single PR, the more time
-    it will take to review those changes.
+1. [Fork the repository](https://github.com/ai-dynamo/dynamo/fork) on GitHub
+2. Clone your fork and set up your development environment following the [Developing Locally](README.md#developing-locally) guide
+3. Set up pre-commit hooks: `pip install pre-commit && pre-commit install`
 
-  - Make sure that the build log is clean, meaning no warnings or
-    errors should be present.
+---
 
-  - Make sure all tests pass.
+## Project Architecture
 
-- Dynamo's default build assumes recent versions of
-  dependencies (CUDA, TensorFlow, PyTorch, TensorRT,
-  etc.). Contributions that add compatibility with older versions of
-  those dependencies will be considered, but NVIDIA cannot guarantee
-  that all possible build configurations work, are not broken by
-  future contributions, and retain highest performance.
+<!-- We were given the feedback that having information on architecture, languages used, etc. would be helpful for external contributors -->
 
-- Make sure that you can contribute your work to open source (no
-  license and/or patent conflict is introduced by your code).
-  You must certify compliance with the
-  [license terms](https://github.com/ai-dynamo/dynamo/blob/main/LICENSE)
-  and sign off on the [Developer Certificate of Origin (DCO)](https://developercertificate.org)
-  described below before your pull request (PR) can be merged.
+Understanding Dynamo's architecture helps you find where to make changes. For the complete picture, see the [Architecture Documentation](docs/design_docs/architecture.md) and [Support Matrix](docs/reference/support-matrix.md).
 
-- Thanks in advance for your patience as we review your contributions;
-  we do appreciate them!
+![Dynamo Architecture](docs/images/architecture.png)
 
-# Coding Convention
+### Core Components
 
-All pull requests are checked against the
-[pre-commit hooks](https://github.com/pre-commit/pre-commit-hooks)
-located [in the repository's top-level .pre-commit-config.yaml](https://github.com/ai-dynamo/dynamo/blob/main/.pre-commit-config.yaml).
-The hooks do some sanity checking like linting and formatting.
-These checks must pass to merge a change.
+| Component | Purpose | Directory |
+|-----------|---------|-----------|
+| **Frontend** | OpenAI-compatible HTTP API server | `components/src/dynamo/frontend/` |
+| **Router** | KV cache-aware request routing with load balancing | `components/src/dynamo/router/` |
+| **Planner** | Real-time performance tuning and worker scaling | `components/src/dynamo/planner/` |
+| **Workers** | Backend engine integrations (vLLM, SGLang, TensorRT-LLM) | `components/src/dynamo/{vllm,sglang,trtllm}/` |
+| **KV Cache Manager** | Multi-tier cache offloading (GPU → CPU → SSD → Object Storage) | `lib/bindings/kvbm/` |
+| **SLA Profiler** | Benchmarking and SLA-driven configuration | `benchmarks/profiler/` |
 
-To run these locally, you can
-[install pre-commit,](https://pre-commit.com/#install)
-then run `pre-commit install` inside the cloned repo. When you
-commit a change, the pre-commit hooks will run automatically.
-If a fix is implemented by a pre-commit hook, adding the file again
-and running `git commit` a second time will pass and successfully
-commit.
+### Communication Planes
 
-# Running Github actions locally
+| Plane | Purpose | Documentation |
+|-------|---------|---------------|
+| **Discovery Plane** | Service registration and discovery across components | [docs/design_docs/distributed_runtime.md](docs/design_docs/distributed_runtime.md) |
+| **Request Plane** | High-performance request routing between components | [docs/design_docs/request_plane.md](docs/design_docs/request_plane.md) |
+| **KV Event Plane** | KV cache event propagation for cache-aware routing | [docs/design_docs/event_plane.md](docs/design_docs/event_plane.md) |
 
-To run the Github actions locally, you can use the `act` tool.
-See [act usage](https://nektosact.com/introduction.html) for more information.
+### Kubernetes Deployment
 
-For example, to run the pre-merge-rust workflow locally, you can use the following command from terminal:
-```
-act -j pre-merge-rust
-```
+| Component | Purpose | Directory |
+|-----------|---------|-----------|
+| **Operator** | CRDs, controllers, and webhooks for K8s-native deployment | `deploy/operator/` |
+| **Helm Charts** | Templated deployment configurations | `deploy/helm/` |
+| **Recipes** | Pre-built deployment configurations for common scenarios | `recipes/` |
 
-Also you can use vscode extension [GitHub Local Actions](https://marketplace.visualstudio.com/items?itemName=SanjulaGanepola.github-local-actions) to run the workflows from vscode.
+### Why These Languages?
 
+| Layer | Language | Why | Directory |
+|-------|----------|-----|-----------|
+| Core Runtime | Rust | Memory safety, zero-cost abstractions, predictable latency | `lib/runtime/` |
+| LLM Engine | Rust | High-throughput token processing, async I/O | `lib/llm/` |
+| KV Block Manager | Rust | Direct memory control for GPU/CPU/SSD offloading | `lib/bindings/kvbm/` |
+| Backend Integrations | Python | Rapid iteration, framework compatibility | `components/src/dynamo/` |
+| Planner & Router | Python | Extensible policies, easy customization | `components/src/dynamo/{planner,router}/` |
+| Kubernetes Operator | Go | K8s controller patterns, client-go ecosystem | `deploy/operator/` |
 
-# Developer Certificate of Origin
+---
 
-Dynamo is an open source product released under
-the Apache 2.0 license (see either
-[the Apache site](https://www.apache.org/licenses/LICENSE-2.0) or
-the [LICENSE file](./LICENSE)). The Apache 2.0 license allows you
-to freely use, modify, distribute, and sell your own products
-that include Apache 2.0 licensed software.
+## Contribution Workflow
 
-We respect intellectual property rights of others and we want
-to make sure all incoming contributions are correctly attributed
-and licensed. A Developer Certificate of Origin (DCO) is a
-lightweight mechanism to do that.
+### When Is a GitHub Issue Required?
 
-The DCO is a declaration attached to every contribution made by
-every developer. In the commit message of the contribution,
-the developer simply adds a `Signed-off-by` statement and thereby
-agrees to the DCO, which you can find below or at [DeveloperCertificate.org](http://developercertificate.org/).
+**Submit a PR directly (no issue needed) if:**
+- Your change is **<100 lines of code** AND addresses a simple, focused concern (typos, simple bug fixes, formatting)
+- **OR** your PR addresses an **existing approved GitHub Issue** (link with "Fixes #123")
 
-```
-Developer Certificate of Origin
-Version 1.1
+**Create a GitHub Issue first for:**
+- Changes ≥100 lines of code
+- New features, architecture changes, or multi-component changes
+- Any change that requires design discussion
+
+### Issue-First Workflow
+
+For larger contributions, follow these steps:
+
+1. **Create a GitHub Issue** – [Open a Contribution Request](https://github.com/ai-dynamo/dynamo/issues/new?template=contribution_request.yml) using the template.
+
+2. **Describe the Problem** – Explain what you're solving, including context, error messages, or use cases.
+
+3. **Propose a Solution** – Include:
+   - **Estimated PR size**: XS / S / M / L / XL / XXL
+   - **Files affected**: Approximate number and components
+   - **Type of change**: Bug fix, new feature, refactoring, or performance improvement
 
-Copyright (C) 2004, 2006 The Linux Foundation and its contributors.
+4. **Get Approval** – Wait for Dynamo maintainers to review and apply the `approved-for-pr` label.
 
-Everyone is permitted to copy and distribute verbatim copies of this
-license document, but changing it is not allowed.
+5. **Submit a Pull Request** – [Open a PR](https://github.com/ai-dynamo/dynamo/compare) that references the issue using GitHub keywords (e.g., "Fixes #123").
 
+6. **Address Code Rabbit Review** – Respond to automated Code Rabbit suggestions, including nitpicks.
 
-Developer's Certificate of Origin 1.1
+7. **Trigger CI Tests** – For external contributors, a Dynamo maintainer must comment `/ok to test <commit-id>` to run the full CI suite, where `<commit-id>` is the short SHA of your latest commit. Fix any failing tests before requesting human review.
 
-By making a contribution to this project, I certify that:
+8. **Request Review** – Add the person who approved your issue as a reviewer. Check [CODEOWNERS](CODEOWNERS) for required approvers based on files modified.
 
-(a) The contribution was created in whole or in part by me and I
-    have the right to submit it under the open source license
-    indicated in the file; or
+> **Note on AI-Generated Code**: While we encourage using AI tools, you must fully understand every change in your PR. Inability to explain submitted code will result in rejection.
 
-(b) The contribution is based upon previous work that, to the best
-    of my knowledge, is covered under an appropriate open source
-    license and I have the right under that license to submit that
-    work with modifications, whether created in whole or in part
-    by me, under the same open source license (unless I am
-    permitted to submit under a different license), as indicated
-    in the file; or
+---
+
+## Code Style & Quality
 
-(c) The contribution was provided directly to me by some other
-    person who certified (a), (b) or (c) and I have not modified
-    it.
+### Pre-commit Hooks
 
-(d) I understand and agree that this project and the contribution
-    are public and that a record of the contribution (including all
-    personal information I submit with it, including my sign-off) is
-    maintained indefinitely and may be redistributed consistent with
-    this project or the open source license(s) involved.
+All PRs are checked against [pre-commit hooks](.pre-commit-config.yaml). Run locally:
+
+```bash
+pre-commit install
+pre-commit run --all-files
 ```
 
-We require that every contribution to Dynamo is signed with
-a Developer Certificate of Origin, this is verified by a required CI check.
-Additionally, please use your real name.
-We do not accept anonymous contributors nor those utilizing pseudonyms.
+### Language Conventions
+
+| Language | Style Guide | Formatter |
+|----------|-------------|-----------|
+| **Python** | [PEP 8](https://peps.python.org/pep-0008/) | `black`, `ruff` |
+| **Rust** | [Rust API Guidelines](https://rust-lang.github.io/api-guidelines/) | `cargo fmt`, `cargo clippy` |
+| **Go** | [Effective Go](https://go.dev/doc/effective_go) | `gofmt` |
+
+### General Guidelines
+
+- Keep PRs focused—one concern per PR
+- Avoid unnecessary complexity
+- No commented-out code
+- Ensure clean builds (no warnings or errors)
+- All tests must pass
+
+### Running GitHub Actions Locally
 
-Each commit must include a DCO which looks like this
+Use [act](https://nektosact.com/) to run workflows locally:
 
+```bash
+act -j pre-merge-rust
 ```
+
+Or use the [GitHub Local Actions](https://marketplace.visualstudio.com/items?itemName=SanjulaGanepola.github-local-actions) VS Code extension.
+
+---
+
+## DCO & Licensing
+
+### Developer Certificate of Origin
+
+Dynamo requires all contributions to be signed off with the [Developer Certificate of Origin (DCO)](https://developercertificate.org/). This certifies that you have the right to submit your contribution under the project's [Apache 2.0 license](LICENSE).
+
+Each commit must include a sign-off line:
+
+```text
 Signed-off-by: Jane Smith <jane.smith@email.com>
 ```
-You may type this line on your own when writing your commit messages.
-However, if your user.name and user.email are set in your git configs,
-you can use `-s` or `--signoff` to add the `Signed-off-by` line to
-the end of the commit message.
 
-⚠️ **Contributor-Friendly DCO Guide:**
-If your pull request fails the DCO check, don't worry! Check out our [DCO Troubleshooting Guide](DCO.md) for step-by-step instructions to fix it quickly.
+Add this automatically with the `-s` flag:
+
+```bash
+git commit -s -m "fix: your descriptive message"
+```
+
+**Requirements:**
+- Use your real name (no pseudonyms or anonymous contributions)
+- Your `user.name` and `user.email` must be configured in git
+
+⚠️ **DCO Check Failed?** See our [DCO Troubleshooting Guide](DCO.md) for step-by-step instructions to fix it.
+
+### License
+
+By contributing, you agree that your contributions will be licensed under the [Apache 2.0 License](LICENSE).
+
+---
+
+## Getting Help
+
+- **Discord**: [Join our community](https://discord.gg/nvidia-dynamo)
+- **Discussions**: [GitHub Discussions](https://github.com/ai-dynamo/dynamo/discussions)
+- **Documentation**: [docs.nvidia.com/dynamo](https://docs.nvidia.com/dynamo/latest/index.html)
+
+Thank you for contributing to Dynamo!

README.md

@@ -363,6 +363,23 @@ Set the environment variable `DYN_LOG` to adjust the logging level; for example,
 
 If you use vscode or cursor, we have a .devcontainer folder built on [Microsofts Extension](https://code.visualstudio.com/docs/devcontainers/containers). For instructions see the [ReadMe](.devcontainer/README.md) for more details.
 
+# Contributing
+
+We welcome contributions! Whether it's bug reports, documentation improvements, or code contributions—every bit helps.
+
+- **[Contributing Guide](CONTRIBUTING.md)** – How to get started
+- **[Report a Bug](https://github.com/ai-dynamo/dynamo/issues/new?template=bug_report.yml)** – Found an issue?
+- **[Feature Request](https://github.com/ai-dynamo/dynamo/issues/new?template=feature_request.yml)** – Have an idea?
+
+# Community
+
+Dynamo thrives on community contributions.
+
+![External Contributors](https://img.shields.io/badge/community_contributors-70%2B-brightgreen)
+![Community PRs](https://img.shields.io/badge/PRs_merged-130%2B-blue)
+
+See our [contributor graph](https://github.com/ai-dynamo/dynamo/graphs/contributors) for the full picture.
+
 <!-- Reference links for Feature Compatibility Matrix -->
 [disagg]: docs/design_docs/disagg_serving.md
 [kv-routing]: docs/router/kv_cache_routing.md