Migrate Contributing Docs to the Docs Site #705

KVSRoyal · 2025-08-16T08:09:20Z

Note

✨ AI-aided PR. I used Cursor for a lot of the tedious copy-pasta-ing. Reviewers should keep an eye out for common AI foibles.

Our contributing documentation currently lives in a lot of different places. Use Cursor to migrate these to the docs site in a new "Contributing" section. The point of this is to improve the onboarding experience by centralizing our docs in one findable location.

Before

Docs scattered in various places:

📁 player/
├── 📄 CONTRIBUTING.md (comprehensive guide - ~100+ lines)
├── 📄 newCONTRIBUTORS.md (first-time contributor guide)
├── 📄 DEV_GUIDE.md (TypeScript/JavaScript development)
├── 📁 android/demo/
│   └── 📄 README.md (Android development guide)
├── 📁 ios/
│   └── 📄 README.md (iOS development guide)
└── 📁 docs/site/src/content/docs/
    └── (no contributing documentation)

📖 Wiki > iOS Development Guide

After

Everything consolidated in the contributing section.

📁 player/
├── 📄 CONTRIBUTING.md (simple stub with links - 18 lines)
└── 📁 docs/site/src/content/docs/contributing/
    ├── 📄 index.mdx (main contributing guide - 109 lines)
    ├── 📄 new-contributors.mdx (first-time contributors - 193 lines)
    ├── 📄 android.mdx (Android development - 67 lines)
    ├── 📄 ios.mdx (iOS development - 354 lines)
    ├── 📄 core-web.mdx (Core & Web development - 205 lines)
    └── 📄 troubleshooting.mdx (real issues only - 77 lines)

Also:

Document a new caching issue affecting iOS builds and how to fix it. Add this to Troubleshooting.
Introduce a Troubleshooting section for common issues.
Leverage Astro components in our migrated docs. I asked Cursor to use components wherever they seemed appropriate.

Impact

This will result in conflicts with Migrate to Bazel 8 #700, which also updates our documentation.
We should delete the Wiki once this PR is merged.

Future Work

These are items we should discuss and align on in a future PR. These came up during PR review.

Thread. Remove GitHub CLI suggestions.
Thread 1, Thread 2. Document forks vs branches.
Thread. Upgrade Android versions to newer.
Thread. Users are probably okay to have multiple SDK versions installed.

Change Type (required)

Indicate the type of change your pull request is:

patch
minor
major
N/A

Does your PR have any documentation updates?

Updated docs
No Update needed
Unable to update docs

codecov · 2025-08-16T08:22:21Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 90.63%. Comparing base (14177bb) to head (eea8c34).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #705   +/-   ##
=======================================
  Coverage   90.63%   90.63%           
=======================================
  Files         341      341           
  Lines       21409    21409           
  Branches     2173     2173           
=======================================
  Hits        19404    19404           
  Misses       1989     1989           
  Partials       16       16

☔ 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.

docs/site/src/content/docs/contributing/new-contributors.mdx

CONTRIBUTING.md

KetanReddy · 2025-08-17T20:33:40Z

docs/site/src/content/docs/contributing/new-contributors.mdx

+   When you're ready to submit a Pull Request, there's a great CLI command for that too:
+
+   ```bash
+   gh pr create


Unless we're going to recommend people download the github cli we probably don't want to have those specific commands here

This stuff was already in the docs and just got moved over. If possible, I'd like to limit this PR to just migration + documenting that iOS cache issue we've been running into a lot. Does that seem reasonable?

I added a "Future Work" section to my PR notes and included this in the list. I'll open an issue for those items once this is merged.

kharrop

Wow! Thanks for a great contributing docs overhaul. Added some minor notes. Question, are you using markdownlint? I can't remember if that's part of this repo.

CONTRIBUTING.md

docs/site/src/content/docs/contributing/troubleshooting.mdx

docs/site/src/content/docs/contributing/index.mdx

docs/site/src/content/docs/contributing/new-contributors.mdx

+ Use more astro components, remove AI content + Document how to fix cache corruption

brocollie08 · 2025-08-18T17:41:05Z

docs/site/src/content/docs/contributing/android.mdx

+
+## Local Development with Android Studio
+
+This setup has been tested on Android Studio Chipmunk (2021.2.1) and Android Studio Giraffe (2022.3.1), though other versions may work as well.


these are realllly old

Can I put this in "Future Work" for a follow-up PR?

If we're touching these docs now should we just clean these up now?

I'd prefer not to because discussing what we should have instead would bloat this PR.

Also, to clarify, I do plan to open a follow-up PR shortly for the other stuff. I just would like to get this in separately first.

Update: I've added this under the "Future Work" section of this PR. I'll cover all of those items in a separate follow-up PR.

I'm trying to keep this PR to just migration stuff to avoid lots of bloat from trying to update docs that haven't been touched in years.

brocollie08 · 2025-08-18T17:42:04Z

docs/site/src/content/docs/contributing/android.mdx

+2. **Configure SDK Build Tools and NDK**
+   - Click on the **SDK Tools** tab
+   - Make sure you have only the following versions installed:
+     - **30.0.3** (SDK Build Tools)


this probably isn't an only

Can I put this in "Future Work" for a follow-up PR?

Update: I've added this under the "Future Work" section of this PR. I'll cover all of those items in a separate follow-up PR.

KetanReddy · 2025-08-18T19:06:04Z

docs/site/src/content/docs/contributing/core-web.mdx

+  "peerDependencies": {
+    "react": "^18.0.0"
+  }


This is a non-internal dependency so it shouldn't be here

Ah, good point. Looks like the AI messed this up when copying over from here and I missed it. I'll change it back to what it was originally.

KetanReddy · 2025-08-18T19:06:26Z

docs/site/src/content/docs/contributing/core-web.mdx

+### Bazel Ignore Configuration
+
+Add the new package's `node_modules` directory to `.bazelignore`:
+
+```
+plugins/example-plugin/core/node_modules
+plugins/example-plugin/react/node_modules
+```


More of a note but this will change with the Bazel 8 structure.

Yeah. Quite a few things change with Bazel 8. I'll sync up with @sugarmanz to see if I can maybe move the docs on that branch out into a separate PR. Then I can hopefully consolidate this change and those changes more easily.

KVSRoyal · 2025-08-19T15:28:47Z

Lots of content changes requested. Moving this PR back to draft because I don't have time to add them.

KVSRoyal requested review from a team as code owners August 16, 2025 08:09

KVSRoyal requested a review from kharrop August 16, 2025 08:09

KetanReddy reviewed Aug 17, 2025

View reviewed changes

docs/site/src/content/docs/contributing/new-contributors.mdx Outdated Show resolved Hide resolved

KetanReddy reviewed Aug 17, 2025

View reviewed changes

docs/site/src/content/docs/contributing/new-contributors.mdx Outdated Show resolved Hide resolved

KetanReddy reviewed Aug 17, 2025

View reviewed changes

CONTRIBUTING.md Show resolved Hide resolved

KetanReddy reviewed Aug 17, 2025

View reviewed changes

kharrop reviewed Aug 18, 2025

View reviewed changes

KVSRoyal force-pushed the PLAYA-9764-contributing-reorg branch from 62efccb to d3f1890 Compare August 18, 2025 14:53

kharrop self-requested a review August 18, 2025 15:13

kharrop previously approved these changes Aug 18, 2025

View reviewed changes

Migrate contributing docs to docs site

ec89e52

+ Use more astro components, remove AI content + Document how to fix cache corruption

KVSRoyal force-pushed the PLAYA-9764-contributing-reorg branch from d3f1890 to ec89e52 Compare August 18, 2025 15:59

brocollie08 reviewed Aug 18, 2025

View reviewed changes

nancywu1 previously approved these changes Aug 18, 2025

View reviewed changes

KetanReddy reviewed Aug 18, 2025

View reviewed changes

Fix AI issue; restore deps example

eea8c34

KVSRoyal dismissed stale reviews from nancywu1 and kharrop via eea8c34 August 18, 2025 19:12

KVSRoyal marked this pull request as draft August 19, 2025 15:27


		## Local Development with Android Studio

		This setup has been tested on Android Studio Chipmunk (2021.2.1) and Android Studio Giraffe (2022.3.1), though other versions may work as well.

Migrate Contributing Docs to the Docs Site #705

Are you sure you want to change the base?

Migrate Contributing Docs to the Docs Site #705

Uh oh!

Conversation

KVSRoyal commented Aug 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Before

After

Impact

Future Work

Change Type (required)

Does your PR have any documentation updates?

Uh oh!

codecov bot commented Aug 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Uh oh!

Uh oh!

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!

kharrop left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

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!

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!

KVSRoyal commented Aug 19, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

KVSRoyal commented Aug 16, 2025 •

edited

Loading

codecov bot commented Aug 16, 2025 •

edited

Loading