Skip to content

Add issue forms, a pull request template and CONTRIBUTING.md - #306

Closed
v0lumehi wants to merge 3 commits into
seedds:mainfrom
v0lumehi:infra-templates
Closed

v0lumehi wants to merge 3 commits into
seedds:mainfrom
v0lumehi:infra-templates

Conversation

@v0lumehi

@v0lumehi v0lumehi commented Oct 26, 2026 •

Copy link
Copy Markdown
Contributor

Update: rebased on main 349abd0. README's For developers line keeps both links (Front ends from #387, CONTRIBUTING.md from here), and CONTRIBUTING's front-end section now links docs/frontends.md, which #387 brought in.

Part of #388 (front ends: one interface between the engine and graphical apps).

Issue forms and a PR template that ask for what a report is traced with

Update (2026-10-27): rebased on main. The last commit adds the NX2Apple link, the feature request form and the front-end section, because front-end requests keep coming in (#104, #244, #264, #332, #374). #387 does the same in README and documents the interface.

Most bug reports reach the maintainer without what a problem is traced with, so the first reply asks for it. In #242 (Breath of the Wild, corrupted picture on an M5), the report had a careful diagnostic summary but no nxnative commit, no macOS version, no environment settings and no full log; the first reply had to ask for all four, plus the shader-build log. #155 and others went the same way.

This adds templates for issues and pull requests, and a short CONTRIBUTING.md. Nothing in the code changes.

  1. .github/ISSUE_TEMPLATE/bug_report.yml, an issue form. The required fields:

    • what happened, plus the expected result as an optional field;
    • the game with its title ID and version;
    • the nxnative commit (git rev-parse --short HEAD);
    • the shader chain version (DMSH_CHAIN in dm/gfx/nvn/dmsh_chain.h, or the b-<version> folder);
    • how it was built and run: a dropdown for the Mac host, the Mac app, an IPA, Xcode, a build by hand, or a failed NSP script;
    • the device and its OS version;
    • settings and environment overrides (env.txt, DM_*), "none" if none;
    • the whole log, with where each build writes it: the Mac app's ~/Library/Logs/nxnative/<title ID>.log and .prev.log, the terminal output, the iPhone's log.txt and log.prev.txt, and dmsh_build.log for graphics problems.

    A required checkbox confirms that nothing attached contains game files, keys or data extracted from a game.

  2. .github/ISSUE_TEMPLATE/game_request.yml. It points at the NSP script's survey (survey.md) as the most useful attachment, and asks how far the game got.

  3. .github/ISSUE_TEMPLATE/config.yml. Blank issues stay allowed. The first link is NX2Apple, for anyone looking for a graphical app to pack and play games, so it shows before any form opens. Then links to README.md (packing, playing, logs) and docs/development.md (porting, debugging).
    3a. .github/ISSUE_TEMPLATE/feature_request.yml. A short feature request form. Its note says that a new graphical front end is a project of its own (NX2Apple is one), that what a front end needs from nxnative is welcome here, and that large changes agree on their scope first.

  4. .github/pull_request_template.md.

    • What and why.
    • What was checked: tests, the games run with their title IDs and versions, devices and OS. For a change to the chain, the host or a tool every game uses, which games were run beyond the one it was made for.
    • Measurements before and after, where they apply.
    • Checkboxes for the reference entry and the symptom index, the chain header, and no game files.
  5. CONTRIBUTING.md. It links AGENTS.md and docs/development.md instead of repeating them. It covers:

    • reporting a problem and never attaching game files;

    • where to start, and one change per PR off main;

    • commit messages, where findings go, the chain header, and the local GPU tests (make -C dm/gfx/tests GAME=<id> run; CI has no Metal 4);

    • that a PR is often taken in squashed or reworked with Co-authored-by and then closed, which is expected.

    • graphical front ends: an app that packs, lists or starts games is a separate project that builds on nxnative's interfaces (the NSP script's --progress json, the settings list a built app carries, environment switches); what it needs from nxnative is welcome as an issue or small PR. The settings screen inside the iPhone app is part of nxnative.

    README's For developers section links it.

Checked

  • test_docs passes: links and anchors, AGENTS.md and guide word limits.
  • The YAML of the four files parses.
  • ci.sh (host tests, CPU gfx tests, every gfx test built, dmhost for three profiles, the iOS compile check, all tool tests): no failures.
  • The forms only render on GitHub once this is on main; I have not seen them rendered in this repository.

The bug report form asks up front for what a problem is traced with:
- the nxnative commit and the shader chain version;
- the game's title ID and version, the device and OS;
- how it was built and run, and any environment overrides;
- the whole log, with where each build writes it.
Issue seedds#242 needed a second round for the commit, the log and the macOS version.

The game request form points at the NSP script's survey. Both forms refuse game files and keys.

The PR template asks what was checked (tests, games, devices) and whether the docs and the symptom index followed. For a change to the chain, the host or a tool every game uses, it asks which games were run beyond the one it was made for.

CONTRIBUTING.md links AGENTS.md and docs/development.md instead of repeating them. It covers reporting, no game files, where findings go, the chain header, local GPU tests, and how changes get in. README's For developers section links it.
…rms first (a new platform, a second implementation of an existing path, or more than about 1,000 lines), one concern per PR, and the supported devices as README names them
…n issue

Requests and PRs for graphical front ends keep coming in (seedds#104, seedds#244, seedds#264,
seedds#332, seedds#374), although README names NX2Apple, a community app that packs
games, keeps a library and starts them with their settings. The mention sits
in "Pack an IPA", where someone about to build a front end does not look.

The issue chooser now lists NX2Apple first among its links, so it shows
before any form opens. A feature request form says that a new front end is a
project of its own and what is welcome here instead: the piece a front end
needs from nxnative. CONTRIBUTING.md has a section on graphical front ends:
the interfaces one builds on (the NSP script's --progress json events, the
settings list a built app carries, environment switches), and that the
settings screen inside the iPhone app is part of nxnative.
seedds added a commit that referenced this pull request Oct 27, 2026
Most bug reports reached the maintainer without what a problem is traced
with, so the first reply asked for it (#242, #155). The bug report form
asks for the game with its title ID and version, the nxnative commit,
the shader chain version, how it was built and run, the device and OS,
the settings and environment overrides, and the whole log. A game
request form points at the NSP script's survey, a feature request form
at front ends' own projects, and the issue chooser at NX2Apple first.

CONTRIBUTING.md says how a change gets in: one change per PR, where
findings go, the shader chain's header, the tests CI cannot run, scope
agreed first for large changes and other platforms, the supported
devices as README names them, front ends as separate projects building
on docs/frontends.md, and that the maintainer often takes a PR in as a
reworked commit crediting its author. README's For developers line
links it.

Updated while landing: front ends can also keep a player's choices in
the app's saved choices; the Mac settings window is part of nxnative
like the iPhone's screen; a Mac app's env.txt location in the bug form;
the PR template asks for the regress.py report AGENTS.md requires; a
conflicting PR may be rebased by the maintainer while taking it in.

Co-authored-by: v0lumehi <[email protected]>
@seedds

seedds commented Oct 27, 2026

Copy link
Copy Markdown
Owner

Thanks, @v0lumehi. This landed on main as 81d53bf, with you as co-author. The forms, the template and CONTRIBUTING.md are as you wrote them, with a few updates for what landed today:

  • CONTRIBUTING, Graphical front ends: a front end can also keep a player's choices as saved choices, which every start reads (Saved choices). The Mac app's settings window (Mac: settings window before the game starts #379) is part of nxnative, like the iPhone's screen.
  • CONTRIBUTING, How changes get in: the maintainer may rebase or rework a conflicting PR while taking it in, rather than asking the author to.
  • Bug form: settings changed in the Mac window, and a Mac app's env.txt location (~/Library/Application Support/nxnative/<title ID>/env.txt).
  • PR template: for a chain, host or shared-tool change, it asks for the scripts/regress.py check --games report that AGENTS.md requires, linked with an absolute URL so the link works inside a PR.

The four forms parse as YAML, and test_docs (links and anchors in every Markdown file) passes. Closing this PR.

@seedds seedds closed this Oct 27, 2026
seedds added a commit that referenced this pull request Oct 27, 2026
…306)

81d53bf's message lists updates made while landing #306, but they were
left unstaged when it was committed, so main got #306 as it was. These
are those updates: front ends can also keep a player's choices as saved
choices; the Mac settings window is part of nxnative like the iPhone's
screen; the bug form names settings changed in the Mac window, a Mac
app's env.txt and variables a front end sets; the PR template asks for
the regress.py report AGENTS.md requires, with an absolute link that
works inside a PR; a conflicting PR may be rebased by the maintainer.

The three issue forms also drop labels: [], which GitHub's issue-forms
schema (SchemaStore github-issue-forms.json) rejects: labels is a
non-empty list or a string when present. All four files now validate
against it and config.yml against github-issue-config.json.

Co-authored-by: v0lumehi <[email protected]>
@seedds

seedds commented Oct 27, 2026

Copy link
Copy Markdown
Owner

Correction: the updates my comment above lists were not in 81d53bf. I left them unstaged when I committed, so 81d53bf is this PR exactly as you wrote it. They landed in 1289f16, which also drops labels: [] from the three forms: GitHub's issue-forms schema rejects an empty list. All four files now validate against SchemaStore's github-issue-forms.json and github-issue-config.json, and GitHub renders each form's preview without an error.

v0lumehi added a commit to v0lumehi/nxnative that referenced this pull request Oct 30, 2026
…API skip

The pull request template and the issue forms from seedds#306 only appear on
GitHub's web pages. gh pr create, gh issue create and the API open a PR or
an issue with whatever body they are given, so an agent never sees them and
nothing told it to follow them: PRs and issues opened by agents came in
with their own structure, without the Checked and Docs sections or the bug
form's commit, chain version and device.

06-dev-loop.md gets a section 8, "Opening an issue or a pull request": a PR
body keeps the template's three sections (What and why, Checked, Docs with
its checkboxes), an issue the matching form's fields as headings in their
order, and nothing from a game in either. AGENTS.md's task table points
there (AGENTS.md stays at its 1,500 words), and CONTRIBUTING.md says the
same for people who open them from the command line.

Checked: test_docs passes (links, anchors, word limits).
Know-It-All-Brother pushed a commit to Know-It-All-Brother/nxnative that referenced this pull request Nov 9, 2026
…eedds#388)

Most bug reports reached the maintainer without what a problem is traced
with, so the first reply asked for it (seedds#242, seedds#155). The bug report form
asks for the game with its title ID and version, the nxnative commit,
the shader chain version, how it was built and run, the device and OS,
the settings and environment overrides, and the whole log. A game
request form points at the NSP script's survey, a feature request form
at front ends' own projects, and the issue chooser at NX2Apple first.

CONTRIBUTING.md says how a change gets in: one change per PR, where
findings go, the shader chain's header, the tests CI cannot run, scope
agreed first for large changes and other platforms, the supported
devices as README names them, front ends as separate projects building
on docs/frontends.md, and that the maintainer often takes a PR in as a
reworked commit crediting its author. README's For developers line
links it.

Updated while landing: front ends can also keep a player's choices in
the app's saved choices; the Mac settings window is part of nxnative
like the iPhone's screen; a Mac app's env.txt location in the bug form;
the PR template asks for the regress.py report AGENTS.md requires; a
conflicting PR may be rebased by the maintainer while taking it in.

Co-authored-by: v0lumehi <[email protected]>
Know-It-All-Brother pushed a commit to Know-It-All-Brother/nxnative that referenced this pull request Nov 9, 2026
…eedds#306)

87311ff's message lists updates made while landing seedds#306, but they were
left unstaged when it was committed, so main got seedds#306 as it was. These
are those updates: front ends can also keep a player's choices as saved
choices; the Mac settings window is part of nxnative like the iPhone's
screen; the bug form names settings changed in the Mac window, a Mac
app's env.txt and variables a front end sets; the PR template asks for
the regress.py report AGENTS.md requires, with an absolute link that
works inside a PR; a conflicting PR may be rebased by the maintainer.

The three issue forms also drop labels: [], which GitHub's issue-forms
schema (SchemaStore github-issue-forms.json) rejects: labels is a
non-empty list or a string when present. All four files now validate
against it and config.yml against github-issue-config.json.

Co-authored-by: v0lumehi <[email protected]>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants