57 review and streamline contributor and developer documentation #169

pbearne · 2026-01-09T19:44:15Z

What?

Closes #57

Why?

…md`, `EXPERIMENTS_DEVELOPER_GUIDE.md`, and `RELEASE_INSTRUCTIONS.md`. Updated `CONTRIBUTING.md` to include revised setup and coding standards.

…EW.md` and add REST API testing documentation

github-actions · 2026-01-09T19:44:25Z

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

Unlinked Accounts

The following contributors have not linked their GitHub and WordPress.org accounts: @pbearne@git.wordpress.org, @hrishikesh2810.

Contributors, please read how to link your accounts to ensure your work is properly credited in WordPress releases.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Unlinked contributors: pbearne@git.wordpress.org, hrishikesh2810.

Co-authored-by: pbearne <pbearne@git.wordpress.org>
Co-authored-by: jeffpaul <jeffpaul@git.wordpress.org>
Co-authored-by: dkotter <dkotter@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

codecov · 2026-01-09T19:47:55Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 47.97%. Comparing base (a876ab6) to head (479e796).
⚠️ Report is 1 commits behind head on develop.

Additional details and impacted files

@@            Coverage Diff             @@
##             develop     #169   +/-   ##
==========================================
  Coverage      47.97%   47.97%           
  Complexity       243      243           
==========================================
  Files             22       22           
  Lines           1430     1430           
==========================================
  Hits             686      686           
  Misses           744      744

Flag	Coverage Δ
unit	`47.97% <ø> (ø)`

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

jeffpaul · 2026-01-12T17:41:28Z

@pbearne would be great to get your GitHub and WPORG accounts linked (see bot message above) as that makes crediting back to WPORG accounts more automated/reliable.

docs/DEVELOPER_GUIDE.md

docs/EXPERIMENTS_DEVELOPER_GUIDE.md

docs/DEVELOPER_GUIDE.md

dkotter · 2026-01-13T16:39:43Z

CONTRIBUTING.md

+composer install && npm i && npm run build
+```
+
+> **Note:** The `wordpress/wp-ai-client` package will be added to `composer.json` once it's officially released. For now, the plugin scaffolding is ready for integration.


This is outdated information. This package is now included in our composer config

dkotter · 2026-01-13T16:40:05Z

CONTRIBUTING.md

+```
+### Quality checks


Would be nice to have a line break between these

CONTRIBUTING.md

dkotter · 2026-01-13T16:41:13Z

CONTRIBUTING.md

+* `develop`: The main development branch.
+* `trunk`: The stable release branch.
+* `release/*`: A branch for a specific release, useful e.g. for applying a hotfix.
+* `feature/*`: A branch for a larger feature that takes multiple iterative PRs towards completion.


We haven't been following this so I'd suggest we remove it

dkotter · 2026-01-13T16:41:38Z

CONTRIBUTING.md

+
+These special branches are protected and are configured more strictly in regards to GitHub workflow configuration.
+
+Branches that you use for implementing a pull request or experimenting can use any naming convention you prefer, _except_ the above. Additionally, please do not use branch names that would easily cause confusion, such as other common main branch names like `main` or `develop`.


We've already mentioned develop above so no need to repeat that here

CONTRIBUTING.md

dkotter · 2026-01-13T16:43:29Z

docs/ARCHITECTURE_OVERVIEW.md

+│       └── Example_Experiment/       # Each experiment in own directory
+│           ├── Example_Experiment.php
+│           └── README.md
+├── admin/                            # Admin interface (planned)


This directory doesn't exist so should be removed from here

dkotter · 2026-01-13T16:43:44Z

docs/ARCHITECTURE_OVERVIEW.md

+│           ├── Example_Experiment.php
+│           └── README.md
+├── admin/                            # Admin interface (planned)
+├── assets/                           # CSS, JS, images


This also doesn't exist

dkotter · 2026-01-13T16:43:59Z

docs/ARCHITECTURE_OVERVIEW.md

+│   ├── RELEASE_INSTRUCTIONS.md       # Release Instructions
+│   ├── TESTING.md                    # Testing strategy
+│   └── TESTING_REST_API.md           # Testing API strategy
+├── languages/                        # Translation files


Doesn't exist

dkotter · 2026-01-13T16:44:59Z

docs/ARCHITECTURE_OVERVIEW.md

+ai/
+├── ai.php                            # Plugin bootstrap
+├── build/                            # Built assets
+├── includes/                         # Core plugin code


Missing the Abilities and Settings directories

Co-authored-by: Darin Kotter <darin.kotter@gmail.com>

…developer-documentation

jeffpaul · 2026-01-16T23:51:18Z

@pbearne I've applied most of the recommended changes here, would you mind handling the rest called out above?

Paul Bearne added 2 commits January 9, 2026 14:36

Split documentation into modular files: added `ARCHITECTURE_OVERVIEW.…

1a57462

…md`, `EXPERIMENTS_DEVELOPER_GUIDE.md`, and `RELEASE_INSTRUCTIONS.md`. Updated `CONTRIBUTING.md` to include revised setup and coding standards.

Update EXPERIMENTS_DEVELOPER_GUIDE.md: link to `ARCHITECTURE_OVERVI…

ab1a37b

…EW.md` and add REST API testing documentation

jeffpaul requested a review from dkotter January 12, 2026 17:40

jeffpaul added this to the 0.2.0 milestone Jan 12, 2026