Find repositories by topic and open the listing pull request for them

[Maximilian-Nesslauer]

Listing your content is a hand-written TOML file today. GitHub can list every repository carrying a given topic, so a scheduled job could find the ones that want to be indexed and open the listing pull request itself.

The topic becomes one generic ksa-index rather than the per-account ksa-index-<username> of RFC 0038.

Only a repository administrator can set a topic at all, so both prove the same thing, that somebody with rights on that repository wants it indexed.

The per-account form additionally bound who may write the listing, and we need to drop that.

How it would run

The bot builds what it can from the repository and opens the pull request here either way.

name, authors, abstract and license come from the repository API. links.forums and compatibility.game_min are required by RFC 0031 and nothing in a GitHub repository carries them, so they come from .github/ksa-content-index.toml, which grows from an ownership marker into a small listing stub.

There should be 2 cases from there:

• The stub has them. The document is complete, the pull request validates and merges itself.
• The stub does not. The pull request is opened as a draft and mentions the repository owner, or its top contributor when the repository belongs to an organization, saying which fields are missing and to add them to that same file. The next tick picks the file up, completes the pull request and lets it merge.

What has to change

• .github/ksa-content-index.toml gains the fields a crawler cannot derive.
• ownership.verify compares ksa-index-<pull request author> today, so it has to learn the generic topic, and decide.py has to accept a pull request the bot opened itself.

[averageksp]

I like the shape of this, but I do not think the generic topic can go into ownership.verify, and I want to flag why before anyone writes the code.

verify(document, login, author_id, api) exists to answer one question: does this account control the authority repo. All three proofs bind to login. If a bare ksa-index counts as a fourth proof, the function stops answering that question at all, because it now returns verified for whoever happened to open the pull request. So once I set ksa-index on my mod's repo to opt in, anyone can open a pull request against my listing, repoint [releases] at their own repo or loosen my [loader] bounds, and it merges itself. The watcher then stamps their archives under my id.

The way out is that the two topics answer different questions. ksa-index-<login> is "this account may write my listing", which is RFC 0038 and should stay as it is. A bare ksa-index is "index me", which is consent, not authority. So keep it out of verify entirely and give decide.py its own narrow rule for the bot: the author is the App, the diff is exactly one new listing document, the authority repo is not a fork, it carries ksa-index, and its [releases] points back at itself. Anything else, including any edit to a listing that already exists, goes down the path we already have. That also means RFC 0038 needs no amendment, since nothing about it changes.

The other thing I would push back on is how much the crawler can actually derive. I compared the repository API against the two listings we have merged:

Field	Repository API	The merged listing
name	KSA-AdvancedFlightComputer / StarMap	Advanced Flight Computer / StarMap
authors	Maximilian-Nesslauer / StarMapLoader (an org)	Maxi / KlaasWhite
abstract	"Advanced orbital mechanics mod for Kitten Space Agency Flight Computer. Hyperbolic transfer targets, autostaging, and m..." / "KSA Mod Loader"	"Extra maneuver planning tools for Kitten Space Agency." / "Mod loader that runs code mods for Kitten Space Agency."
license	MIT / MIT	MIT / MIT

One of the four survives contact, and authors is wrong both times. The AFC repo description even advertises autostaging, which is a different mod.

Then there is what the issue does not list at all: id, type, [loader], tags, the extra [links], and for StarMap the whole [install], [provides] and [provides.configure] block, without which a manager cannot install a loader at all. Add those up and "the stub has them" really means the stub is the listing.

Which is fine, it is just a different pitch. The win is not that we derive a listing from a repo, it is that an author writes one file in their own repository instead of a pull request against this one, which is what 0038 wanted in the first place. I would describe it that way and let the index fill in the two or three fields it genuinely knows.

Two things worth adding while you are in there. The id should come from the release archive's top-level folder, because that is the identity the game sees, and the stamper already derives it in derive_root; if it disagrees with the stub, reject rather than guess. And a code mod is detectable from the [StarMap] section of the archive's mod.toml, so we can refuse to publish one with no [loader] instead of shipping a listing that installs cleanly and then silently never loads.

Questions I would want answered before implementation:

• the second tick after the stub changed, which is an edit to an existing listing and the hardest case for the rule above
• what the bot does when the derived id is already taken by a different repository, which must not become a pull request that edits somebody's listing
• when a draft nobody completes gets closed
• what happens when the topic is removed

Last small one: "top contributor" on an org repo will ping people who have no say over the listing. If the stub is the source of truth anyway, let it name who to mention.

[Maximilian-Nesslauer]

@averageksp

If a bare ksa-index counts as a fourth proof, the function stops answering that question at all, because it now returns verified for whoever happened to open the pull request.

Didnt you just argue the oposite way on https://discord.com/channels/1439383096813158702/1532471092252381244/1537843354363236444 ?

ksa-index-<login> is "this account may write my listing", which is RFC 0038 and should stay as it is. A bare ksa-index is "index me", which is consent, not authority.

You wrote https://discord.com/channels/1439383096813158702/1532471092252381244/1537843739601535179 in discord. We can always create an new RFC that does update this. We should decide it in the file in the mods repo instead.

What a crawler can derive

One of the four survives contact, and authors is wrong both times.

KlaasWhite is still the author of StarMap so i wanted to credit him instead of his org.

Add those up and "the stub has them" really means the stub is the listing.

Correct. The index can only fill in what it can know. Stuff that cant be derived from the repo must be filled in manually.

So once I set ksa-index on my mod's repo to opt in, anyone can open a pull request against my listing, repoint [releases] at their own repo or loosen my [loader] bounds, and it merges itself.

Hmm true. What do you propose to fix this?

a code mod is detectable from the [StarMap] section of the archive's mod.toml, so we can refuse to publish one with no [loader] instead of shipping a listing that installs cleanly and then silently never loads.

Agreed on the goal, but the signal has to be a different one. EntryAssembly defaults to the mod id when the whole [StarMap] section is absent, and RuntimeMod.TryCreateMod skips a mod without a matching <EntryAssembly>.dll without an error, which is how part and config mods pass through. So a code mod can carry no [StarMap] section at all, and the detectable fact is that the archive contains <EntryAssembly or id>.dll.

Your questions

the second tick after the stub changed, which is an edit to an existing listing and the hardest case for the rule above

It stops being a special case if the bot rule is stated as an equality rather than as a set of conditions: the submitted document equals the stub in the repository the listing points at. The pull request is then trusted because its source is trusted, not because of who opened it, and a second tick is just another document that has to match its source. Which repository "points at" means is the base version for an edit, per the rule above.

what the bot does when the derived id is already taken by a different repository, which must not become a pull request that edits somebody's listing

The bot opens nothing at all, and keeps one issue per collision naming both repositories. It must never touch a listing whose base authority is a different repository, which is the same rule as above, applied before the pull request exists rather than after. Renaming is the author's decision and the folders names must be different by the KSA game cdesign, because the id is the folder name the game sees.

when a draft nobody completes gets closed

I would say 30 days without a stub change, with the closing comment naming the missing fields, and no further pull request until the stub changes. The crawler is idempotent anyway.

what happens when the topic is removed

The same as RFC 0038 already says for the per-account form: it revokes the proof for future checks, and listings already in the index stay listed. Removing a listing stays a steward action through index-status.toml for now.

"top contributor" on an org repo will ping people who have no say over the listing. If the stub is the source of truth anyway, let it name who to mention.

Agreed. lets just use the stub as the source of truth.

[averageksp]

Yes, and I changed my mind an hour later reading ownership.py: the topic sits on your repo, so taking the name out opens it to everyone instead of to whoever you named.

Agreed on the file. If every listing needs a stub anyway, the commit 0038 exists to avoid is one you make regardless, so topic becomes discovery and file becomes consent plus who may write.

The fix:

1. Bare topic never enters verify().
2. Bot pull requests: your equality rule, as a re-derivation. Rebuild the document from repo plus stub, compare, same shape as the release checks re-deriving with the stamper.
3. An edit verifies against the base version's authority, not the submitted one. You wrote that for the bot, it has to apply to everyone: today I can repoint your [releases] at my repo and get verified against my own repo. Worth landing before any crawler.

You are right on EntryAssembly, so the signal is the archive containing <EntryAssembly, defaulting to the id>.dll.

Agreed on the rest.