write-documentation

name	撰写文档 Write Documentation
description	### Write Documentation This command is invoked when the code changes for a feature or bugfix are complete on a branch (branched from `develop`) and documentation is the only remaining task. The AI should discover what changed, categorize it, and write the appropriate documentation entries.

Workflow

Step 0: Determine the author

Use git log develop...HEAD --format="%an <%ae>" to list commits on the current branch that are not in develop. If the branch has extra commits, use the author name(s) from those commits as the user's identity for CREDITS.md and Whats-New.md. If there are no extra commits or the author cannot be determined from commit information, ask the user directly for their identity before proceeding.

Step 1: Discover what changed

Run git diff develop...HEAD --stat to see which files were modified. Then inspect the diffs in detail using git diff develop...HEAD (or git diff develop...HEAD -- <specific files>) to understand the nature of each change. Key things to identify:

• New/changed INI keys (tags) — look for .Read(exINI, ...) calls in LoadFromINIFile / LoadBeforeTypeData etc.
• New/changed hooks — look for DEFINE_HOOK, DEFINE_JUMP, DEFINE_PATCH macros.
• New types/classes — look for new files in src/New/ or new ExtData classes.
• Whether the change is a new feature, an enhancement of existing behavior, a bugfix, a UI change, an AI/scripting change, or something miscellaneous.

Step 2: Categorize the change

Determine which doc pages need updating:

Change type	Where to document
New feature (brand new functionality)	New ### section in the appropriate primary doc page, inserted in dictionary (alphabetical) order among existing sibling ### headings
Enhancement of existing game behavior that adds new INI tags	New ### section in the appropriate primary doc page, likewise in alphabetical order
Enhancement/bugfix of existing game behavior with no new INI tags	A bullet point under ## Bugfixes and miscellaneous in docs/Fixed-or-Improved-Logics.md
User interface change (new hotkey, display, sidebar, tooltip)	docs/User-Interface.md
AI, scripting, trigger, or mapping change	docs/AI-Scripting-and-Mapping.md
Uncategorized change	docs/Miscellanous.md

Primary doc page mapping:

• Most game logic features → docs/New-or-Enhanced-Logics.md
  • Within this file, ## headings are categories (e.g., ## Buildings, ## Projectiles, ## Warheads). Place new ### sections under the appropriate category, sorted alphabetically.

Additionally, every change requires:

• docs/Whats-New.md — changelog entry.
• CREDITS.md — credit the author.

Breaking changes (changes to vanilla behavior, changes to already-released Phobos behavior, renamed/removed INI tags, savegame incompatibilities, etc.) must also be recorded in docs/Whats-New.md under ## Migration (breaking changes), inside the ### <version> section for the version currently being developed on develop. Place the entry under #### Changes to vanilla behavior (for vanilla behavior changes) or #### Changes to Phobos behavior (for Phobos behavior changes / tag renames or removals). See Step 6 for the exact format.

Step 3: Draft the documentation text — user review required before writing

Before writing any documentation, draft the descriptive text and present it to the user for review. Use the following format for the draft:

### <Feature Name>

- <Brief meaning of the feature.>
  - (tab-indented) <INI key> controls/determines/is used for <explanation>.

Two styles for the first bullet point:

• New feature (brand new functionality):

  - Now you can <do something>. (新功能)
  

• Enhancement of existing behavior (patches/improves vanilla logic):

  - In vanilla, <describe the problem>. Now you can <describe the fix/enhancement>.
  

Wait for the user to approve the drafted text before proceeding to write it into the actual doc files.

Step 4: Write the main documentation

After user approval, write the approved text into the appropriate doc file. For sections in docs/New-or-Enhanced-Logics.md or similar, insert the new ### section in alphabetical order among existing sibling headings under the correct ## category. Look at existing sibling ### headings to determine the correct insertion point.

Continue with the INI code block following existing conventions from the README's "How to read code snippets" section:

; which section the entries should be in
; can be a freeform name - in this case the comment would explain what it is
; if no comment to be found - then it's a precise name
[SOMENAME]           ; BuildingType
; KeyName=DefaultValue ; accepted type with optional explanation
; if there's nothing to the right of equals sign - the default value is empty/absent
; if these keys have had their value set, they can only be set to their default
; unset state again by setting the value to <default>, <none> or none
; for list of values only <default> clears the entire list
; if the default value is not static - it's written and explained in a comment
UIDescription=<none> ; CSF entry key
```

Key rules for INI documentation:

• Use ```ini fenced code blocks.
• Section header comment format: [SOMENAME] followed by spaces then ; ObjectType (e.g., ; BuildingType, ; TechnoType, ; WarheadType, ; SuperWeaponType).
• For global sections use the literal section name: [General], [AudioVisual], [CombatDamage], [Radiation], [AI], etc.
• Key name, equals sign, default value (or blank if empty), spaces, semicolon, type description.
• Boolean types are documented as ; boolean.
• Integer types as ; integer.
• Floating point types as ; double or ; float.
• Pointer types as ; AnimType (just the game class name, not full C++ type).
• List types as ; list of TechnoType etc.
• If the INI key name contains dots, it maps naturally (e.g. KeyName.SubKey stays as-is in docs).

When there are many related keys, group them logically within the same section and INI block. Put them in the order they appear in the INI section.

Step 5: Chinese translation

After the English documentation has been written and confirmed, produce a Chinese translation of the new section(s). Present the Chinese text to the user for review and confirmation. Update the corresponding .po files in docs/locale/zh_CN/LC_MESSAGES/ after the user approves the translation.

Step 6: Write docs/Whats-New.md entry

Whats-New entries go under ## Changelog, inside the ### <version> section for the version currently being developed on develop.

Finding the right version section:

• Inspect src/Phobos.version.h (VERSION_MAJOR/VERSION_MINOR, and PRERELEASE_SUFFIX if defined) to identify the version develop is working towards.
• In docs/Whats-New.md under ## Changelog, locate the matching ### <version> section (e.g. ### 0.6). The currently-active section is the one whose {dropdown} block carries the :open: option; older sections omit it.
• If no matching section exists yet, create one directly below ## Changelog (above the previous version), using the {dropdown} format shown below with :open: so it is the expanded one. Move the :open: flag from the previously-active section to the new one.

Section format (each version's changelog is wrapped in a MyST dropdown; the active one is left open):

### <version>

```{dropdown} Click to show
:open:

#### New:
- <feature description> (by <AuthorName>)

#### Vanilla fixes:
- <fix description> (by <AuthorName>)

#### Phobos fixes:
- <fix description> (by <AuthorName>)

#### Fixes / interactions with other extensions:
- <fix description> (by <AuthorName>)
```

Pick the correct subsection based on the change type:

• #### New: — new features / enhancements of existing behavior that add new INI tags.
• #### Vanilla fixes: — vanilla engine bugfixes.
• #### Phobos fixes: — bugfixes for Phobos-introduced logic.
• #### Fixes / interactions with other extensions: — fixes involving Ares / other libs interop.

Entry format — a single bullet, phrasing matching existing entries, credited using the author identity from Step 0:

- <feature description matching the phrasing used in other entries> (by <AuthorName>)

User-facing RA2MD.INI settings — if the new INI keys are user settings in RA2MD.INI (not rulesmd/artmd), additionally append them to the ## New user settings in RA2MD.INI section (a top-level ## section, separate from ## Changelog):

[Phobos]
NewKeyName=true                  ; boolean

Renamed / removed INI tags and other breaking changes — do not record these in ## Changelog. They belong in ## Migration (breaking changes) under the matching ### <version> section, inside #### Changes to Phobos behavior (for tag renames/removals or Phobos behavior changes) or #### Changes to vanilla behavior (for vanilla behavior changes). Tag renames use the format seen in existing entries:

- `[Section] -> OldName` -> `[Section] -> NewName`

Step 7: Write CREDITS.md entry

Use the author identity determined in Step 0. Find the author's section in CREDITS.md. If the author doesn't have a section yet, create one. Add a bullet describing the contribution:

- **AuthorName (GitHubUsername)**:
  - Feature description matching the phrasing used in other entries

Do not skip the CREDITS entry unless the user explicitly says to skip it.

Step 8: Review and confirm

After writing all entries, present a summary to the user showing which files were modified and what was added.