docs: describe source commit anchoring

This commit is contained in:
Abdessamad Derraz committed 2026-08-07 16:23:15 +02:00
1 parent 1add4d577b
commit 6493d8f17d
1 file changed
+8 -1
+8 -1
View File
@@ -163,6 +163,12 @@ files:
source_ref: Source/Core/Core/Boot/Boot_BS2Emu.cpp:42 source_ref: Source/Core/Core/Boot/Boot_BS2Emu.cpp:42
``` ```
Record `source_commit` when profiling: upstream code moves, and a
`source_ref` line number only stays checkable against the commit it was
read at. Profiles written before this field existed carry `profiled_date`
and `core_version` instead; they gain `source_commit` as they are
re-verified.
### Writing style ### Writing style
Notes in a profile describe what the core does, kept focused on: Notes in a profile describe what the core does, kept focused on:
@@ -255,6 +261,7 @@ even if documentation mentions it.
| `upstream` | no | original emulator repository URL | | `upstream` | no | original emulator repository URL |
| `profiled_date` | yes | date of source analysis | | `profiled_date` | yes | date of source analysis |
| `core_version` | yes | version analyzed | | `core_version` | yes | version analyzed |
| `source_commit` | no | upstream commit SHA the source was read at; anchors every `source_ref` line number |
| `display_name` | no | full display name (e.g. "Sega - Mega Drive (BlastEm)") | | `display_name` | no | full display name (e.g. "Sega - Mega Drive (BlastEm)") |
| `systems` | yes | list of system IDs this core handles | | `systems` | yes | list of system IDs this core handles |
| `cores` | no | list of upstream core names for buildbot/target matching | | `cores` | no | list of upstream core names for buildbot/target matching |
@@ -283,7 +290,7 @@ even if documentation mentions it.
| `hle_fallback` | true if a high-level emulation path exists | | `hle_fallback` | true if a high-level emulation path exists |
| `category` | `bios` (default), `game_data`, `bios_zip` | | `category` | `bios` (default), `game_data`, `bios_zip` |
| `region` | geographic region (e.g. `north-america`, `japan`) | | `region` | geographic region (e.g. `north-america`, `japan`) |
| `source_ref` | source file and line number (e.g. `boot.cpp:42`) | | `source_ref` | source file and line number (e.g. `boot.cpp:42`), read at the profile's `source_commit` when set |
| `path` | destination path relative to system directory | | `path` | destination path relative to system directory |
| `description` | what this file is | | `description` | what this file is |
| `note` | additional context | | `note` | additional context |