docs(contribute): Add contributor guide #481

mkmeral · 2026-01-26T23:36:53Z

Description

Adds a new Contribute section to the docs site, providing clear guidance for developers who want to contribute to Strands.

This implements the contributor documentation strategy discussed in #1535. The key insight: we need to clearly separate "how to contribute" from "what the community has built" — and make it easy for contributors to find the right path based on what they want to do.

What's new

Contribute section (docs/contribute/)

Overview page with table-based navigation ("I want to..." format)
Core SDK — Contributing bug fixes and features to sdk-python/sdk-typescript
Documentation — Contributing to docs
Feature Proposals — ADR process for larger features
Extensions — Building your own tools, model providers, hooks, session managers using our template

ADR process (adrs/)

README with process and template
Extensibility strategy (ADR-0001)
Community health strategy (ADR-0002)

Team documentation (team/)

README indexing TENETS.md, DECISIONS.md, API_BAR_RAISING.md
These are linked from contribute docs via GitHub URLs

Why this structure

From the discussion: contributors need different paths based on their intent. Someone fixing a bug has different needs than someone building a Slack integration. The table format on the overview page makes it easy to find the right guide.

Extensions get their own guide because we don't accept external tools to the core repo (security/maintenance burden). Instead, we provide a template and list community packages in the catalog.

Related Issues

Implements #1535

Type of Change

New content
Structure/organization improvement

Checklist

I have read the CONTRIBUTING document
My changes follow the project's documentation style
I have tested the documentation locally using mkdocs serve
Links in the documentation are valid and working

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

- Add community index page with contribution router - Add contributing guides: core-sdk, documentation, feature-proposals - Add extensions docs: ecosystem overview, publishing guide, best practices - Update community-packages.md to be the catalog page

Updates documentation for comprehensive community contribution support - Add introductory context to each major section explaining purpose and navigation - Expand core-sdk.md with detailed development workflow, pre-commit hooks explanation, and quality requirements - Enhance documentation.md with comprehensive style guidelines and code example requirements - Improve feature-proposals.md with detailed RFC process timeline and template guidance - Expand extensions/index.md with characteristics of each tier and partnership process details - Enhance publishing.md with step-by-step guidance, semantic versioning examples, and discoverability tips - Improve best-practices.md with detailed tables showing why principles matter and implementation guides - Add lead-in sentences to all tables and lists throughout for better context - Include cross-references to related documentation and reference materials - Match collaborative 'we' style consistent with existing user-guide documentation

Refactor community documentation to be more action-oriented - Rename 'extensions' to 'publishing' to be more concrete and actionable - Rewrite index.md with clear 'I want to...' sections instead of tables - De-emphasize tier system - move to brief context section - Add strands.my reference to community catalog - Update all internal links from extensions/ to publishing/ - Simplify 'Why we don't accept tools' section to be more concise - Retitle files: 'Publishing your component' instead of 'extensions' - Add 'Community resources' section with catalog link

- Separate Community (catalog/ecosystem) from Contribute (how to help) - Add new contribute section with core-sdk, documentation, feature-proposals, extensions guides - Create ADR process in adrs/ folder with template - Add team docs (TENETS, DECISIONS, API_BAR_RAISING) to root team/ folder - Add extensibility and community health strategy as ADRs - Update feature proposals to require issue first, ADR merge = go-ahead - Fix broken links and naming conventions (strands-agents topic) - Remove timeline commitments from ADR process - Delete old community/contributing and community/publishing folders

strands-agent · 2026-01-26T23:41:25Z

Documentation Deployment Complete

Your documentation preview has been successfully deployed!

Preview URL: https://d3ehv1nix5p99z.cloudfront.net/pr-481/

- Fix docs setup: use pip install -e . instead of requirements.txt - Add hatch run prepare and npm run check as single commands for quality checks - Add 'Find something to work on' section with ready-for-contribution links - Link feature proposals from breaking changes guidance - Rename template repo to strands-python-extension-template

strands-agent · 2026-01-27T03:47:43Z

Documentation Deployment Complete

Your documentation preview has been successfully deployed!

Preview URL: https://d3ehv1nix5p99z.cloudfront.net/pr-481/

strands-agent · 2026-01-27T04:00:37Z

Documentation Deployment Complete

Your documentation preview has been successfully deployed!

Preview URL: https://d3ehv1nix5p99z.cloudfront.net/pr-481/

- Reframe extensions.md as publishing guide, not building guide - Slim down to essentials with link to template - Update index.md to match new framing - Fix arrow link patterns in community-packages.md

strands-agent · 2026-01-27T20:16:26Z

Documentation Deployment Complete

Your documentation preview has been successfully deployed!

Preview URL: https://d3ehv1nix5p99z.cloudfront.net/pr-481/

Unshure · 2026-01-29T19:31:34Z

adrs/README.md

nit: Would you be open to naming this just decision records? Makes it more generic for a place to put these things, not just architecture related items.

Unshure · 2026-01-29T19:32:59Z

adrs/0001-extensibility-ecosystem-strategy.md

@@ -0,0 +1,302 @@
+# Strands Agents: Extensibility & Ecosystem Strategy


nit: In line with my other comment, this isnt really an sdk architecture decision, but a decision on how we interface with the community.

Unshure · 2026-01-29T19:33:25Z

adrs/README.md

+
+## What is an ADR?
+
+An ADR is a design document that captures an important architectural decision along with its context and consequences. Once approved and merged, it becomes part of the project's decision history.


This just sounds like an RFC. How is this different from an RFC?

Unshure · 2026-01-29T19:34:57Z

adrs/README.md

+6. **Get approval** — Once approved and merged, implement the feature
+7. **Reference the ADR** — Link to it in your implementation PR
+
+## ADR template


The two included adrs dont follow this template... should we just remove this template? Or make the template more generic so that the included adrs do follow it?

adrs/0001-extensibility-ecosystem-strategy.md

adrs/0002-community-health-strategy.md

strands-agent · 2026-01-29T20:10:03Z

Documentation Deployment Complete

Your documentation preview has been successfully deployed!

Preview URL: https://d3ehv1nix5p99z.cloudfront.net/pr-481/

strands-agent · 2026-01-29T21:00:20Z

Documentation Deployment Complete

Your documentation preview has been successfully deployed!

Preview URL: https://d3ehv1nix5p99z.cloudfront.net/pr-481/

zastrowm · 2026-01-29T21:04:48Z

docs/community/community-packages.md

@@ -1,54 +1,57 @@
-# Community Packages
+# Community catalog


The sidebar still has the old title

zastrowm · 2026-01-29T21:08:04Z

docs/contribute/index.md

+| I want to... | What it involves | Guide |
+|--------------|------------------|-------|
+| Fix a bug | Check for existing issues, submit a PR with tests that verify your fix | [Core SDK](./contributing/core-sdk.md) |
+| Add a new feature | For small changes, open an issue first. For larger features, go through the ADR process to align on direction | [Feature Proposals](./contributing/feature-proposals.md) |


This isn't the ADR process; I think this needs to be re-pitched as the RFC process or something

zastrowm · 2026-01-29T21:15:18Z

docs/contribute/contributing/core-sdk.md

@@ -0,0 +1,142 @@
+# Contributing to core SDK


The position of Core SDK seems a bit odd here - what are we trying to target by using "Core" - it's sort of distracting

Maybe Core libraries or something if you're trying to make it distinct from tools?

zastrowm · 2026-01-29T21:17:15Z

docs/contribute/contributing/core-sdk.md

+
+This guide walks you through contributing to sdk-python and sdk-typescript. We'll cover what types of contributions we accept, how to set up your development environment, and how to submit your changes for review.
+
+## What we accept


We could call out the labels; many of the PRs that we reject or ignore are because we didn't really refine or declare that we wanted it. We have labels for features that are open to be contributed

zastrowm · 2026-01-29T21:19:11Z

docs/contribute/contributing/core-sdk.md

+    - Run `npm run test:all` to test in both Node.js and browser environments
+    - Check [CONTRIBUTING.md](https://github.com/strands-agents/sdk-typescript/blob/main/CONTRIBUTING.md) for detailed requirements
+
+## Find something to work on


This should be higher up and and part of the initial critiera

zastrowm · 2026-01-29T21:20:50Z

docs/contribute/contributing/documentation.md

+| Typo fixes | Spelling, grammar, and formatting corrections | Fix misspelled function names, correct punctuation |
+| Clarifications | Rewording confusing sections | Simplify complex explanations, add missing context |
+| New examples | Code samples and tutorials | Working code showing real-world usage |
+| API reference | Improvements to reference documentation | Better parameter descriptions, return value docs |


This is in code; should we have that here? It seems out of place

zastrowm · 2026-01-29T21:21:23Z

docs/contribute/contributing/documentation.md

+| Clarifications | Rewording confusing sections | Simplify complex explanations, add missing context |
+| New examples | Code samples and tutorials | Working code showing real-world usage |
+| API reference | Improvements to reference documentation | Better parameter descriptions, return value docs |
+| New guides | Complete tutorials or concept pages | Step-by-step workflows, architecture explanations |


We should have a row for community extensions - that's hard coded in the docs right now

zastrowm · 2026-01-29T21:23:25Z

docs/contribute/contributing/documentation.md

+
+Code examples are critical—they show developers exactly what to do. Always test your examples before submitting.
+
+**Requirements:**


I'd unbold "Requirements" - the hbolding is a b it overused IMHO

zastrowm · 2026-01-29T21:25:03Z

docs/contribute/contributing/feature-proposals.md

+
+Not every contribution needs a design document. Use this process for changes that have broad impact or require significant time investment.
+
+| Write a design document for | Skip the design process for |


This table doesn't really make sense - it's more that we have two separate lists (side by side) but we have it in table format.

Can we turn this into side-by-side instead - a table leads me to go left right left right instead which is confusing when I'm trying to understand "When to do X" and "When not to do Y"

zastrowm · 2026-01-29T21:27:26Z

docs/contribute/contributing/extensions.md

+|-----------|---------|------------|
+| **Tools** | Add capabilities to agents—call APIs, access databases, interact with services | [Custom tools](../../user-guide/concepts/tools/custom-tools.md) |
+| **Model providers** | Integrate LLM APIs beyond the built-in providers | [Custom model providers](../../user-guide/concepts/model-providers/custom_model_provider.md) |
+| **Hook providers** | React to agent lifecycle events like invocations, tool calls, and model calls | [Hooks](../../user-guide/concepts/agents/hooks.md) |


"React and respond to" - React seems like it's more "read-only"

mkmeral and others added 5 commits January 7, 2026 00:17

Merge branch 'main' into docs/community-contributor-guide

0c8103a

mkmeral temporarily deployed to auto-approve January 26, 2026 23:37 — with GitHub Actions Inactive

mkmeral changed the title ~~docs(community): Add contributor guide~~ docs(contribute): Add contributor guide Jan 26, 2026

mkmeral temporarily deployed to auto-approve January 27, 2026 03:43 — with GitHub Actions Inactive

docs: add code of conduct and security reporting links

219ea10

mkmeral temporarily deployed to auto-approve January 27, 2026 03:52 — with GitHub Actions Inactive

fix: simplify add package section in community packages

2f49e68

mkmeral temporarily deployed to auto-approve January 27, 2026 03:56 — with GitHub Actions Inactive

mkmeral added 2 commits January 27, 2026 14:50

docs: simplify extensions guide and update contribute section

0c6d504

- Reframe extensions.md as publishing guide, not building guide - Slim down to essentials with link to template - Update index.md to match new framing - Fix arrow link patterns in community-packages.md

fix(contribute): small improvements

696d343

mkmeral temporarily deployed to auto-approve January 27, 2026 20:12 — with GitHub Actions Inactive

yonib05 previously approved these changes Jan 29, 2026

View reviewed changes

Unshure reviewed Jan 29, 2026

View reviewed changes

mkmeral added 2 commits January 29, 2026 14:58

Merge branch 'main' into docs/community-contributor-guide

2c0049c

fix: remove adrs folder

4ff1371

mkmeral dismissed yonib05’s stale review via 4ff1371 January 29, 2026 20:05

mkmeral temporarily deployed to auto-approve January 29, 2026 20:05 — with GitHub Actions Inactive

fix(proposals): Update feature proposals based on designs folder changes

0aa8b32

mkmeral temporarily deployed to auto-approve January 29, 2026 20:56 — with GitHub Actions Inactive

zastrowm requested changes Jan 29, 2026

View reviewed changes

		@@ -0,0 +1,302 @@
		# Strands Agents: Extensibility & Ecosystem Strategy


		## What is an ADR?

		An ADR is a design document that captures an important architectural decision along with its context and consequences. Once approved and merged, it becomes part of the project's decision history.


		This guide walks you through contributing to sdk-python and sdk-typescript. We'll cover what types of contributions we accept, how to set up your development environment, and how to submit your changes for review.

		## What we accept


		Code examples are critical—they show developers exactly what to do. Always test your examples before submitting.

		Requirements:


		Not every contribution needs a design document. Use this process for changes that have broad impact or require significant time investment.

		\| Write a design document for \| Skip the design process for \|

docs(contribute): Add contributor guide #481

Are you sure you want to change the base?

docs(contribute): Add contributor guide #481

Uh oh!

Conversation

mkmeral commented Jan 26, 2026

Description

What's new

Why this structure

Related Issues

Type of Change

Checklist

Uh oh!

strands-agent commented Jan 26, 2026

Documentation Deployment Complete

Uh oh!

strands-agent commented Jan 27, 2026

Documentation Deployment Complete

Uh oh!

strands-agent commented Jan 27, 2026

Documentation Deployment Complete

Uh oh!

strands-agent commented Jan 27, 2026

Documentation Deployment Complete

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!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

strands-agent commented Jan 29, 2026

Documentation Deployment Complete

Uh oh!

strands-agent commented Jan 29, 2026

Documentation Deployment Complete

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!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants