Skip to content

docs: split README into a landing page plus Documentation~ pages - #227

Merged
bobbyg603 merged 9 commits into
mainfrom
docs/split-readme-documentation
Aug 27, 2026
Merged

docs: split README into a landing page plus Documentation~ pages#227
bobbyg603 merged 9 commits into
mainfrom
docs/split-readme-documentation

Conversation

@bobbyg603

@bobbyg603 bobbyg603 commented Aug 20, 2026 •
edited
Loading

Copy link
Copy Markdown
Member

Closes #224
Closes #179

Note

Rebased past #225. This branch has been synced with main since #225 (native multi-attachment) squash-merged. That squash made main and this branch diverge on three code files this PR never touches — Runtime/BugSplat.cs and both Apple bridges — which were resolved to main verbatim. The diff against main is now docs-only; no .cs or .mm file appears in it.

Documentation~/api.md carries #225's Attaching Files to Native Crash Reports section, which was written into the README after this PR's original split and relocated here (heading demoted ### → ##, and its #playerlog-and-privacy link still resolves in-file). That is the one place this branch holds content that never existed in the 499-line original, and it is why the eight pages now total 408 lines rather than the 384 recorded below.

The 499-line README is now a 142-line landing page plus eight Documentation~/ pages. Prose moved verbatim — only heading levels and links changed — so the diff is a move-and-relink, not a rewrite.

Section → destination mapping

Every ##/### in the original README, and where it landed. Nothing was dropped.

Original section Lines Destination
Banner + badges 1–16 README.md
## 👋 Introduction 18–24 README.md
## 🏗 Installation (+ ### OpenUPM, ### Git) 26–42 README.md
## 🧑‍🏫 Sample 44–73 README.md
## 🧰 Player Settings 75–81 README.md
## ⚙️ Configuration 83–101 README.md
## ⌨️ Usage (intro) 103–105 Documentation~/usage.md
### Adding Metadata 107–150 Documentation~/usage.md
### Try/Catch Reporting 152–187 Documentation~/usage.md
### Preventing Repeated Reports 189–213 Documentation~/usage.md
### Background Thread Exceptions 215–223 Documentation~/usage.md
### Unobserved Task Exceptions 225–231 Documentation~/usage.md
### Windows Crashes 233–238 Documentation~/usage.md
### Windows Symbols 240–244 Documentation~/windows.md ⟵ regrouped
### Support Response 246–307 Documentation~/usage.md
## 🧭 Platform Support 309–329 README.md
## 🤖 Android 331–341 Documentation~/android.md
### ANR Reporting 343–345 Documentation~/android.md
## 🍎 iOS 347–353 Documentation~/ios.md
### Hang Detection 355–357 Documentation~/ios.md
## 🖥 macOS 359–365 Documentation~/macos.md
## 🪟 Windows 367–383 Documentation~/windows.md
### Windows Hang Detection 385–389 Documentation~/windows.md
### Windows Error Reporting 391–418 Documentation~/windows.md
### Migrating from 4.x 420–429 Documentation~/migrating-from-4x.md ⟵ regrouped
## 🧩 API (intro) 431–433 Documentation~/api.md
### BugSplatManager 435–441 Documentation~/api.md
### BugSplat Options 443–465 Documentation~/api.md
### Player.log and privacy 467–475 Documentation~/api.md
### BugSplat Environment Variables 477–482 Documentation~/symbol-upload.md
### Symbol Upload Credentials 484–495 Documentation~/symbol-upload.md
## 🧑‍💻 Contributing 497–499 README.md

Two sections were regrouped out from under headings they did not belong to:

  • Windows Symbols was a ### under Usage but is entirely Windows setup, so it now sits on the Windows page, right after the paragraph that already pointed at it.
  • Migrating from 4.x was nested under ## 🪟 Windows even though only one of its six bullets is Windows-related. It is package-wide and now has its own page, which is also what CHANGELOG.md links to.

Everything else kept its original parent. Every ## became the page's # and every ### became ##; GitHub's slugger ignores heading level, so this preserves every anchor target.

Content accounting. A script matched every non-blank line of the original against the new files: 335 of 335 placed, 0 dropped. The only lines not present in the original are the 8 breadcrumbs, the 📚 Documentation table, the 🔑 Symbol Upload page title and its one-line intro, and 10 lines whose only change is a rewritten link (each verified 1:1 against its original). Line totals: 499 → 142 (README) + 384 (eight pages, including breadcrumbs and per-page titles).

Images. All 16 image references are GitHub user-content URLs, so no files moved. Each travelled with the section it illustrates: 13 stayed in the README (banner, badges, sample walkthrough, player settings, configuration), 2 went to android.md (player and build settings), and 1 to usage.md (the support-response screenshot). 13 + 2 + 1 = 16, none lost.

Anchor-link fixes

The 14 anchors from the issue map as follows. Rather than eyeball these, I scraped the rendered heading ids off the live GitHub page, wrote a slugger that reproduces all 35/35 of them exactly, then ran it over every markdown file in the repo. Final state: 41 relative/anchor links across 12 markdown files, 0 problems.

Old link Found in New target
#-player-settings README (Sample tip) unchanged — section stayed in README
#-usage README (Sample) Documentation~/usage.md
#adding-metadata Usage intro #adding-metadata (now in-file in usage.md)
#trycatch-reporting Usage intro #trycatch-reporting (in-file in usage.md)
#preventing-repeated-reports Usage intro #preventing-repeated-reports (in-file in usage.md)
#preventing-repeated-reports API note usage.md#preventing-repeated-reports
#preventing-repeated-reports sample README ../../Documentation~/usage.md#preventing-repeated-reports
#-windows Usage intro windows.md
#-windows Windows Crashes windows.md
#-windows Platform Support Documentation~/windows.md
#-android / #-ios / #-macos Platform Support Documentation~/android.md / ios.md / macos.md
#background-thread-exceptions Platform Support Documentation~/usage.md#background-thread-exceptions
#background-thread-exceptions API table usage.md#background-thread-exceptions
#symbol-upload-credentials Platform Support Documentation~/symbol-upload.md#symbol-upload-credentials
#symbol-upload-credentials Windows Symbols symbol-upload.md#symbol-upload-credentials
#symbol-upload-credentials Migration guide symbol-upload.md#symbol-upload-credentials
#symbol-upload-credentials Env var table (×2) #symbol-upload-credentials (in-file in symbol-upload.md)
#windows-error-reporting Windows intro #windows-error-reporting (in-file in windows.md)
#windows-error-reporting sample README ../../Documentation~/windows.md#windows-error-reporting
#windows-symbols Windows intro #windows-symbols (in-file in windows.md)
#playerlog-and-privacy Options table #playerlog-and-privacy (in-file in api.md)
README.md#migrating-from-4x CHANGELOG.md Documentation~/migrating-from-4x.md

Three links were already broken before this PR

The mechanical check surfaced breakage that predates the split:

  1. README.md → [usage](#-usage). GitHub renders ## ⌨️ Usage as id #️-usage — the U+FE0F variation selector in ⌨️ survives slugging, so the plain-hyphen #-usage never resolved. Plain emoji (🪟, 🤖, 🍎) are stripped entirely, which is why #-windows and friends worked; emoji carrying U+FE0F (⌨️, ⚙️) and ZWJ sequences (🧑‍🏫, 🧑‍💻) do not behave the same way. Fixed here by pointing at the file.
  2. Samples~/my-unity-crasher/README.md → ../../../README.md#windows-error-reporting and #preventing-repeated-reports. Both used three ../ where the repo root is two up, so neither resolved on GitHub. Fixed and re-pointed at their new homes.

To keep this class of bug from recurring, the new pages avoid emoji-heading anchors entirely: cross-file links target either a file or a plain-text ## heading, never an emoji # heading.

External deep links

I fetched docs.bugsplat.com/integrations/game-development/unity. It deep-links into this README eight times:

GitBook link Status after this PR
#-player-settings ✅ still works — Player Settings stayed in the README
#%E2%9A%99%EF%B8%8F-configuration ⚠️ already broken before this PR (encodes ⚙️-configuration; the real id is ️-configuration). The section itself stayed in the README, so the correct anchor still exists — GitBook's link was simply wrong.
#usage ❌ already broken before this PR (real id is ️-usage). Now also relocated → should become Documentation~/usage.md.
#windows ❌ already broken before this PR (real id is -windows). Now also relocated → should become Documentation~/windows.md.
#adding-metadata ❌ newly broken by this PR → Documentation~/usage.md#adding-metadata
#trycatch-reporting ❌ newly broken by this PR → Documentation~/usage.md#trycatch-reporting
#preventing-repeated-reports ❌ newly broken by this PR → Documentation~/usage.md#preventing-repeated-reports
.../Samples~/my-unity-crasher/Scripts/ErrorGenerator.cs ✅ unaffected

So three GitBook links break here and two more were already dead. All five land on the README's top rather than 404ing, and the new 📚 Documentation table is one click from there, so nobody hits a dead end. I can't fix bugsplat-docs from this repo — see the follow-up below.

I found no blog or support content deep-linking these anchors beyond the GitBook page.

documentationUrl decision: leave it on GitBook (no change)

package.json still points documentationUrl at https://docs.bugsplat.com/integrations/game-development/unity. Reasoning:

  • Unity's Package Manager opens documentationUrl in a browser. A Documentation~/ folder is not a URL, so it can't be the value; the only alternative would be swapping one hosted page (GitBook) for another (a github.com/.../blob/main/Documentation~/... link).
  • That swap trades a searchable, versionless docs home BugSplat controls and can fix without a package release for a branch-pinned blob URL that has to be kept in sync with releases. That's a downgrade, not an upgrade.
  • The genuine problem is that GitBook is stale, not that the manifest points at it. Repointing the manifest would paper over the divergence instead of fixing it, and would leave the stale page still ranking in search.

Documentation~/ is not wasted either way: Unity surfaces it for local and embedded packages, and it is what people browsing the repo or the installed package on disk actually read.

Documentation~/ ships to consumers ✅

Verified, not assumed:

  • No .meta files. The trailing tilde keeps Unity from importing the folder, so none are needed and none were created (ls -a Documentation~/ shows only the eight .md files). This matches Samples~/, which likewise has no Samples~.meta.
  • No exclusion anywhere. The repo has no .npmignore and package.json has no files field; .gitignore lists only build outputs (symbol-upload-*, BugSplat.zip, .DS_Store).
  • npm pack --dry-run confirms it. All eight pages appear in the tarball manifest (285 files total, alongside the 32 Samples~ entries that already prove a ~ folder survives packing). That tarball is what OpenUPM publishes; git-URL installs get the whole repo regardless.

GitBook divergence — now being fixed separately

Update: a bugsplat-docs PR is in flight covering this, stacked on bugsplat-docs#327 so the whole Unity 5.0.0 docs sync ships as one PR there. No issue was filed; the work went straight to a PR. The survey below is what prompted it.

Out of scope for this repo. The GitBook page's headings are: Installation, Sample, Player Settings, Configuration, Usage, Android, iOS, macOS, API, User Feedback, Contributing. Compared with this repo it is missing Windows entirely — no native Windows crash reporting, no Windows Error Reporting, no Windows hang detection, no Windows symbols — plus no Platform Support matrix, no ANR reporting, no iOS hang detection, no background-thread or unobserved-task exceptions, no Player.log privacy note, no symbol upload credentials, and no 4.x migration guide. It also has a User Feedback section that the README does not.

Proposed issue: "Make the repo the canonical Unity docs and reduce GitBook to a pointer." Decide which copy is canonical (the repo is now clearly more current and more complete), rewrite the GitBook page as a short overview that links into Documentation~/, and fix the three deep links this PR breaks plus the two already-dead ones. That removes the two-repo edit that produced the #166 drift batch.

Nothing deleted

No content was judged obsolete, so nothing is proposed for deletion. Every original line is in the tree.

Pre-existing defects observed while moving (not fixed here)

Flagging rather than silently fixing, so the diff stays readable as a pure move. All four predate this PR:

(Line numbers below predate the api.md additions noted at the top; the text is unchanged.)

  1. Documentation~/api.md line 25 (was README:453) — "overridden by call to post" should be Post, inconsistent with the four rows around it. (raised by Copilot)
  2. Documentation~/api.md line 29 (was README:457) — "Should BugSplat a screenshot and upload it" is missing its verb; should be "Should BugSplat capture a screenshot". (raised by Copilot)
  3. Trailing whitespace on four lines — README.md 3 and 99, Documentation~/api.md 11 and 19. All carried over verbatim from the original.
  4. GitBook's #usage, #windows, and #⚙️-configuration deep links were already dead before this PR (see the External deep links table above).

Worth a small copy pass; happy to fold 1–3 into this PR if you'd rather not carry them.

CI

These results are from the original split commit. The branch has been pushed several times since (syncing #225 and the post-squash main merge), and CI is re-running on the current head — a docs-only diff shouldn't move any of them, but treat the table as the last confirmed full pass rather than the current state:

Check Result
StandaloneLinux64 ✅ pass (3m16s)
StandaloneWindows64 ✅ pass (2m59s)
StandaloneOSX ✅ pass (3m13s)
WebGL ✅ pass (4m22s)
Compile iOS ✅ pass (2m38s)
Compile Android ✅ pass (3m23s)
CodeQL — Analyze (actions) ✅ pass (1m0s)
CodeQL — Analyze (csharp) ✅ pass (1m27s)

(The four * test results entries report skipping, which is their normal state on this workflow and matches main.)

Docs-only: no .cs, no package.json version bump, no Runtime/, Editor/, or Samples~/ code touched. Per #224 this should land before #168 so the re-shot screenshots get placed into their final homes once.

🤖 Generated with Claude Code

bobbyg603 and others added 2 commits August 19, 2026 21:29
@bobbyg603 @claude
fix: stop the sample from defeating the CapturePlayerLog opt-out
1c594f5 
Samples~/my-unity-crasher/Scripts/BugSplatSettings.cs called
AttachNativeLogFile(Application.consoleLogPath) unconditionally at Start.
Native init already attaches the console log when CapturePlayerLog is on, and
BugSplat_AddAttachment does not de-duplicate, so Windows native reports shipped
Player.log twice - and a user who unticked CapturePlayerLog got it anyway,
because the sample re-attached it behind the setting's back. The sample exists
to demonstrate that privacy control, so the call is gone; CapturePlayerLog
handles the file on both Windows and macOS.

AttachNativeLogFile held the same trap for any consumer. It called
BugSplat_AddAttachment directly and never touched nativePlayerLogAttached, the
flag SetNativePlayerLogAttachment uses to decide whether the log is already
attached, so attaching the console log by hand desynced it: a later
CapturePlayerLog = true attached the file a second time, and a later
CapturePlayerLog = false early-returned as a no-op and left it attached,
defeating the opt-out for the rest of the session. AttachNativeLogFile now
routes the console log path through SetNativePlayerLogAttachment, which
de-duplicates and keeps the flag in sync; any other path is attached directly
as before. iOS is unaffected - _attachNativeLogFileIos is an empty stub - and
Android has no bridge call at all.

Removing the sample call leaves AttachNativeLogFile undemonstrated in the
sample. A purpose-made second file was considered and rejected: the macOS
bridge holds a single log path, so attaching another file there silently
replaces Player.log, and the crash scenario menu is a table of failure modes
with no natural home for an API demo. The API is documented in the README
instead, including the macOS single-slot behavior.

Verified by compiling Runtime/** against Unity's managed assemblies under every
platform define permutation the change touches - Windows, macOS, iOS, Android,
WebGL, Linux, each with and without UNITY_EDITOR: 0 errors, and no warnings
beyond the pre-existing CS0649 never-assigned-field ones.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@bobbyg603 @claude
docs: split README into a landing page plus Documentation~ pages
3fb332b 
The README had grown to 499 lines serving four audiences at once: evaluators,
first-time integrators, per-platform implementers, and reference readers. The
pitch was buried above 200 lines of platform setup, and there was no way to link
someone to just the Windows story.

The README keeps what a front page needs — banner, introduction, installation,
the sample walkthrough, player settings, configuration, and the platform support
matrix — plus a table routing into the new pages. It is now 142 lines.

Documentation~ takes the deep reference, split along the existing ## seams:

  usage.md             metadata, try/catch, throttling, background thread and
                       unobserved task exceptions, support responses
  android.md           Crashpad setup, symbols.zip, ANR reporting
  ios.md               PLCrashReporter setup, dSYMs, hang detection
  macos.md             PLCrashReporter setup, dSYMs
  windows.md           native setup, symbols, hang detection, WER
  api.md               BugSplatManager, BugSplatOptions, Player.log and privacy
  symbol-upload.md     credentials, resolution order, environment variables
  migrating-from-4x.md the 5.0.0 breaking changes

Prose moves verbatim; only heading levels and links changed. Two sections moved
out from under headings they did not belong to: "Windows Symbols" was under Usage
and is now on the Windows page, and "Migrating from 4.x" was nested under Windows
despite being package-wide, so it is now its own page.

The trailing tilde keeps Unity from importing the folder, so no .meta files are
needed. npm pack confirms all eight pages ship to consumers.

Anchor links were re-pointed at their new homes and verified mechanically against
GitHub's own slugs. That check also caught three links that were already broken
before this change: the README's [usage](#-usage) (the real anchor for "⌨️ Usage"
retains the U+FE0F variation selector) and two ../../../README.md links in the
sample README that were one level too deep.

Closes #224
Closes #179

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Copilot AI lite review requested due to automatic review settings August 20, 2026 01:34
@bobbyg603 bobbyg603 added this to the 5.0.0 milestone Aug 20, 2026
Copilot AI reviewed Aug 20, 2026
View reviewed changes

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This PR restructures the repository documentation by turning the large monolithic README into a shorter landing page and moving detailed reference material into UPM-conventional Documentation~/ pages, while updating internal links to match the new layout.

Changes:

  • Split long-form sections from README.md into dedicated Documentation~/ markdown pages.
  • Updated cross-file links/anchors in the repo (including the sample README) to point at the new documentation locations.
  • Updated CHANGELOG.md to link to the new migration guide location.

Reviewed changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated 1 comment.

Show a summary per file
File Description
Samples~/my-unity-crasher/README.md Updates relative links to Windows Error Reporting and usage throttling docs in Documentation~/.
README.md Converts README into a landing page and adds a documentation index table with updated links.
Documentation~/usage.md New usage/reference page moved from README (metadata, try/catch, throttling, threading/task exceptions, support response).
Documentation~/windows.md New Windows-specific page (native crash reporting, symbols, hang detection, WER).
Documentation~/android.md New Android-specific page (Crashpad setup, symbols.zip, ANR reporting).
Documentation~/ios.md New iOS-specific page (PLCrashReporter setup, dSYM upload, hang detection).
Documentation~/macos.md New macOS-specific page (PLCrashReporter setup, symbolication notes).
Documentation~/api.md New API/options reference page moved from README.
Documentation~/symbol-upload.md New symbol upload credentials/env var reference page moved from README.
Documentation~/migrating-from-4x.md New migration guide page moved from README.
CHANGELOG.md Updates the “Migrating from 4.x” link to the new docs page.
Suppressed comments (1)

Documentation~/api.md:29

  • The CaptureScreenshots row is missing a verb ("Should BugSplat a screenshot..."); this is grammatically incorrect and may confuse readers.
| CaptureScreenshots | Should BugSplat a screenshot and upload it when Post is called |

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

Comment thread Documentation~/api.md
| Description | A default description that can be overridden by call to Post.|
| Email | A default email that can be overridden by call to Post.|
| Key | A default key that can be overridden by call to Post.|
| Notes | A default general purpose field that can be overridden by call to post |

@bobbyg603 bobbyg603 Aug 20, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Correct on both counts, and both predate this PR — they are verbatim from README lines 453 and 457 on main (line 29 is worse than the casing: "Should BugSplat a screenshot" is missing its verb).

Leaving them as-is deliberately. #224 scopes this change to a move-and-relink and asks that relocated prose not be reworded, so that the diff stays reviewable as a pure move. Mixing copy edits into 400 relocated lines would make it impossible to tell moved text from changed text at review time.

Both are noted in the PR description under "Pre-existing defects observed while moving" for a follow-up copy pass.

Copilot AI review requested due to automatic review settings August 20, 2026 01:59
@bobbyg603
bobbyg603 changed the base branch from main to fix/216-sample-player-log-attach August 20, 2026 02:00
@bobbyg603

bobbyg603 commented Aug 20, 2026

Copy link
Copy Markdown
Member Author

Restacked on #225, which also edits README.md — merged it in and re-based this PR on its branch so the two don't collide (GitHub retargets this to main automatically once #225 merges).

#225 added an Attaching Files to Native Crash Reports section to the README, in the block this PR moved to Documentation~/api.md. Rather than leave it stranded at the old location, I relocated it into api.md with the heading level adjusted to match the page (### → ##); its [Player.log and privacy](#playerlog-and-privacy) link still resolves because that heading lives in the same file. Also extended the README's API table row to mention native attachments.

Copilot AI reviewed Aug 20, 2026
View reviewed changes

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated no new comments.

Suppressed comments (2)

Documentation~/ios.md:5

  • This sentence says to set UseNativeCrashReportingForIos / UploadDebugSymbolsForIos on the BugSplatManager instance, but these settings are fields on BugSplatOptions (see Runtime/Client/BugSplatOptions.cs:67-71). This is likely to mislead integrators configuring iOS crash reporting.
The bugsplat-unity plugin supports native crash reporting on iOS via [bugsplat-apple](https://github.com/BugSplat-Git/bugsplat-apple), which uses PLCrashReporter to capture crashes via Mach exception handling. To configure crash reporting for iOS, set the `UseNativeCrashReportingForIos` and `UploadDebugSymbolsForIos` properties to `true` on the BugSplatManager instance.

Documentation~/android.md:5

  • This sentence says to set UseNativeCrashReportingForAndroid / UploadDebugSymbolsForAndroid on the BugSplatManager instance, but these settings are fields on BugSplatOptions (see Runtime/Client/BugSplatOptions.cs:73-77). This is likely to confuse users about where to configure Android crash reporting.
The bugsplat-unity plugin supports crash reporting for native C++ crashes on Android via Crashpad. To configure crash reporting for Android, set the `UseNativeCrashReportingForAndroid` and `UploadDebugSymbolsForAndroid` properties to `true` on the BugSplatManager instance.

@bobbyg603 @claude
fix: track native attachments as a set instead of one Player.log bool
63025e5 
AttachNativeLogFile special-cased Application.consoleLogPath and routed it
through SetNativePlayerLogAttachment. That fixed the #216 symptom but left the
root cause: the SDK mirrored native attachment state in a single bool that
tracks one file, while the native layers model something else entirely --
Windows keeps an unbounded set with no de-duplication, and the macOS bridge
kept one global slot that plain assignment replaced.

Any write that bypassed the bool desynced it, and the string guard was ordinal
equality, so Path.GetFullPath, a different casing, or forward slashes all
missed it and reproduced #216. Worse, on macOS attaching a file and then
setting CapturePlayerLog = false cleared the slot and destroyed the user's
attachment, and the guard gave AttachNativeLogFile a main-thread dependency it
never had by reading Application.consoleLogPath.

Model the state instead: an ordered, de-duplicated list of the full paths the
SDK has told the native layer to attach, compared case-insensitively on
Windows. CapturePlayerLog becomes an ordinary caller of the same attach/detach
primitive with a console log path cached at construction, so no public method
touches the Unity API, and the string special case disappears. Detaching the
player log now removes only the player log.

The Apple bridges become genuinely multi-attachment so the C# model has
something real to drive. macOS swaps its single _logFilePath for a list and
returns one BugSplatAttachment per tracked file; the 10 MB tail read, lazy
existence checking, and installing the delegate before start are preserved,
and the delegate is now installed unconditionally so it is in place when start
processes reports left by the previous session. iOS replaces the no-op stub
with the same delegate -- its stated reason for existing, that the delegate
suppresses attributes, was never true after the S3 upload flow landed
(BugSplat-Git/bugsplat-apple#70). iOS multi-attachment stays inert until #70
ships and BugSplat.xcframework is re-vendored, since the vendored iOS slice
still gates attachmentsForBugSplat: behind TARGET_OS_OSX.

Both bridges now own their tracked paths in an NSMutableArray. The old code
assigned an autoreleased NSString straight into a static, which dangles when
the file is compiled without ARC -- Unity's generated Xcode projects do not
enable it by default.

Closes #216

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Copilot AI review requested due to automatic review settings August 24, 2026 14:52
Copilot AI reviewed Aug 24, 2026
View reviewed changes

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated no new comments.

bobbyg603 and others added 3 commits August 27, 2026 11:12
@bobbyg603 @claude
fix!: move public types out of the global namespace (#226)
d6547d9 
Every public type a UPM package declares in the global namespace is injected
into the global scope of every project that installs it, so the package's
names compete with the consumer's own. Four package types did this:

  Editor/PostBuild.cs                      BuildPostprocessors
  Editor/BugSplatOptionsEditor.cs          BugSplatOptionsEditor
  Editor/BugSplatSymbolUploadCredentials.cs BugSplatSymbolUploadCredentials
  Runtime/Manager/BugSplatRef.cs           BugSplatRef

The Editor types move to BugSplatUnity.Editor and BugSplatRef to
BugSplatUnity.Runtime.Manager, matching the namespace every other file in
those directories already uses. Three sample scripts (BugSplatCube,
BugSplatSettings, LockOrientation) had the same problem and move to Crasher,
where their three siblings already live; the sample is copied into the
consumer's own Assets folder on import, so those names land in Assembly-CSharp.

BugSplatOptionsEditor's base class is now spelled UnityEditor.Editor: inside
BugSplatUnity.Editor the simple name Editor binds to the enclosing member
namespace before any using directive is consulted.

BugSplatRef is an implementation detail - BugSplatManager holds one in a
private field and nothing else in the package or its public API mentions the
type - so it becomes internal, and its BugSplat property loses the public
setter it never needed (#132 F8). The test assembly reaches it through the
existing InternalsVisibleTo.

No file or .meta GUID changes, so scene and asset references, which Unity
serializes by script GUID, are unaffected. Discovery of the moved editor
types is by attribute ([PostProcessBuild], [CustomEditor]), which does not
consider namespaces.

This is a breaking change to the public API surface and only free while 5.0.0
is unreleased.

Closes #155

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
@bobbyg603 @claude
chore: vendor bugsplat-apple 3.5.0 for iOS multi-attachment support
35dd04c 
Updates BugSplat.xcframework and BugSplat-macOS.dylib to the 3.5.0
release, which ships bugsplat-apple#70. That un-gates
attachmentsForBugSplat: on iOS (it was declared inside TARGET_OS_OSX
before), so the plural delegate this branch already implements is now
actually called there.

The framework adds BugSplatFeedbackResult.h to every slice; nothing was
removed. The five macOS framework symlinks are restored through the git
index because the extraction host cannot create them on disk.

Drops the stale comment in the iOS bridge explaining why
attachmentsForBugSplat: was left undeclared, and the README caveat that
iOS multi-attachment awaited a framework update.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@bobbyg603
Merge remote-tracking branch 'origin/fix/216-sample-player-log-attach…
0efe73d 
…' into sync/227c

# Conflicts:
#	README.md
Copilot AI review requested due to automatic review settings August 27, 2026 15:21
Copilot AI reviewed Aug 27, 2026
View reviewed changes

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated no new comments.

Base automatically changed from fix/216-sample-player-log-attach to main August 27, 2026 15:56
@bobbyg603
Merge remote-tracking branch 'origin/main' into sync/227d
3b31c8a 
# Conflicts:
#	Editor/IOS/ObjC/BugSplatBridge.mm
#	README.md
#	Runtime/BugSplat.cs
#	Runtime/Plugins/macOS/BugSplatBridgeMac.mm
Copilot AI review requested due to automatic review settings August 27, 2026 15:58
Copilot AI reviewed Aug 27, 2026
View reviewed changes

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated no new comments.

@bobbyg603 bobbyg603 mentioned this pull request Aug 27, 2026
Draft
@bobbyg603
bobbyg603 merged commit 547ede7 into main Aug 27, 2026
14 checks passed
@bobbyg603
bobbyg603 deleted the docs/split-readme-documentation branch August 27, 2026 16:16
@bobbyg603 bobbyg603 mentioned this pull request Aug 27, 2026
Open
96 tasks
bobbyg603 added a commit that referenced this pull request Aug 28, 2026
@bobbyg603 @claude
docs: name both prerequisites for the native Player.log attachment
07ccb3e 
Review feedback. The sentence read as though CapturePlayerLog alone attaches
Player.log to native crash reports, but the whole path sits inside
if (useNativeLibIos) - it needs UseNativeCrashReportingForIos as well. Since
CapturePlayerLog defaults to true, the native option is in practice the operative
one, which made the omission the more misleading half.

Also says explicitly that managed .NET reports attach the log through the
reporter and are unaffected by the native setting, which is the confusion the
original sentence invited.

Applied to macos.md too. That sentence predates this stack - it came in with the
docs split in #227 - and carries exactly the same gap. It is out of this PR's
nominal scope, but the two files are parallel docs read side by side, and fixing
one while leaving its twin wrong a line away is worse than either state.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KCtsoKMLq2WeYvsPFivVAA
bobbyg603 added a commit that referenced this pull request Aug 29, 2026
@bobbyg603 @claude
fix: attach Player.log to native iOS crash reports (#231)
4195a02 
* fix: attach Player.log to native iOS crash reports

CapturePlayerLog never reached the iOS native reporter. The bridge installed
the attachment delegate before -start, and its comment said why, but the log
path itself was only registered later, through _attachNativeLogFile after the
constructor returned. By then -start had already processed the previous
session's pending reports and asked the delegate for attachments - and the
tracked list was still empty.

Native crash reports upload on the launch after the crash, so attachments were
requested at the one moment the list was guaranteed to be empty. Native iOS
crash reports have therefore never carried Player.log, even with
CapturePlayerLog on by default. Managed exception reports were unaffected;
they attach the log through the .NET reporter.

Pass the path into _startBugSplat and track it before -start, which is what the
macOS branch already did.

Both Apple start functions now take the same arguments, so the last
platform-specific DllImport in the Apple block collapses too.

Verified by compiling the iOS bridge against the vendored xcframework with the
iOS SDK, clean under both ARC and manual retain/release, and by building and
running a macOS player to confirm the shared signature did not regress it.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KCtsoKMLq2WeYvsPFivVAA

* refactor: hold the attachment lock at the constructor insertion sites too

Review feedback: nativeAttachmentPaths doubles as the lock object for
AttachNativeLogFile and DetachNativeLogFile, but the constructor added the
player log to it without taking that lock.

No race is possible today - the instance has not been published to another
thread while its constructor runs - so this is not a fix for a live bug. It is
about the invariant. "Every mutation of nativeAttachmentPaths happens under its
lock" is auditable at a glance; "...except two constructor sites, which are safe
because of publication timing" is not, and it decays the moment construction or
publishing changes shape.

The lock is uncontended here and taken once at init, so the cost is nothing.

Applied at both Apple sites rather than only the iOS one this PR adds. The macOS
insertion had the same gap, and leaving one locked and one not would be worse
than either state.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KCtsoKMLq2WeYvsPFivVAA

* docs: name both prerequisites for the native Player.log attachment

Review feedback. The sentence read as though CapturePlayerLog alone attaches
Player.log to native crash reports, but the whole path sits inside
if (useNativeLibIos) - it needs UseNativeCrashReportingForIos as well. Since
CapturePlayerLog defaults to true, the native option is in practice the operative
one, which made the omission the more misleading half.

Also says explicitly that managed .NET reports attach the log through the
reporter and are unaffected by the native setting, which is the confusion the
original sentence invited.

Applied to macos.md too. That sentence predates this stack - it came in with the
docs split in #227 - and carries exactly the same gap. It is out of this PR's
nominal scope, but the two files are parallel docs read side by side, and fixing
one while leaving its twin wrong a line away is worse than either state.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KCtsoKMLq2WeYvsPFivVAA

---------

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

Copilot code review Copilot
Copilot review effort, defaults to Lite
Applies to this pull request for everyone.Learn more about Copilot code review.
Copilot left review comments
@daveplunkett daveplunkett daveplunkett approved these changes

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

5.0.0

Development

Successfully merging this pull request may close these issues.

Split the 499-line README into a landing page plus Documentation~ pages H2: Add Documentation~ folder

3 participants

@bobbyg603 @daveplunkett