How to Wrangle Metadata for KSP2

Background

Metadata Wranglers are in charge of making sure individual mods install correctly. Each file from the mod should be installed to the correct location, and all dependencies should be accounted for.

• How does CKAN work
• Adding a mod to the CKAN#advanced
• https://github.com/KSP-CKAN/CKAN/blob/master/Spec.md
• http://status.ksp-ckan.space/ (Uncheck the "KSP" checkbox at the top to view only KSP2 mods)
• Subscribe to notifications from both metadata repos
  • https://github.com/KSP-CKAN/KSP2-NetKAN (netkans, the templates that CKAN uses to find releases and fills in)
  • https://github.com/KSP-CKAN/KSP2-CKAN-meta (ckans, the stamped files for each release, only edit this for old releases)

Reviewing pull requests

A pull request is a set of pending changes on a temporary git branch to be reviewed and merged into main.

Incoming pull requests accumulate here: https://github.com/KSP-CKAN/KSP2-NetKAN/pulls

• Do not add any mod without the author's (or current maintainer's) permission. A pull request from SpaceDock means the uploader clicked the CKAN checkbox, which we consider to be a request to add the mod, but make sure the uploader is the author! For other mods, ask the author on the forum, Discord, etc., and paste the approval into the PR if received. If the author says no, then thank them for their time and stop bothering them.
• Don't merge anything without a green checkmark
  
  
• Click the Files tab to see warnings
  • Add review comments for human-generated PRs if something's not right
• Click the Checks tab for verbose validation output under "Test modified netkans"
  • Make sure the installed files are right under "Installing (mod name)"
  • If you get an error because a dependency isn't compatible with the same game versions, you can add ckan compat 0.1.1.0 to the PR body to simulate User guide#choosing compatible game versions
  • You can re-run the Checks manually if you change something other than the netkan or if the mod is updated
    
• To make more changes:
  1. Click the Files tab
  2. Click the ellipsis (...) button → Edit file
  3. Change the file contents
  4. Commit to the PR's branch
  5. The Checks will re-run automatically, and you should receive an email if there are errors
• Add labels if you need to communicate something to the other Wranglers (like waiting for mod author approval or waiting for a new release)
• Clicking merge adds the changes to the main branch, where users will see them
  • This will queue a request for the bot to re-check the mod with the new changes, which may be delayed up to 15 minutes if it's busy, and GitHub adds another 5-minute delay after that before users get the changes

Updating a netkan

To change an existing netkan, create a pull request:

1. Click a netkan from https://github.com/KSP-CKAN/KSP2-NetKAN/tree/main/NetKAN
2. Click the pencil icon
3. Make changes
4. Commit to a new branch
5. Start a pull request
6. Put the reason for your changes into the pull request body so other team members can reference it in the future
7. Submit the pull request and make sure the validation on the Checks tab looks OK

Metadata best practices

• New netkans should be in YAML format
• Many fields can be retrieved from SpaceDock, so let them be
  • name
  • abstract
  • resources.homepage
  • resources.repository
• See Suggested Tags for how to maintain the tags property; it was originally written for KSP1 but should be mostly still applicable for KSP2.
• Always have an install property because we're going to have to change the default install stanza (install identifier to BepInEx/plugins) eventually
• Don't install bundled dependencies; add a depends clause instead
• If you're not sure about anything, ask other team members. It's better to delay for a day or two than to break users' installs and have to clean things up.

Keeping track of new game versions

We have two files containing lists of all the game versions in JSON format, which are used by the compatible versions dialog, the modpack editing tab, and certain staging and validation checks in Netkan. SpaceDock has a scheduled task that imports the list automatically, so adding a version to these files will also add it to SpaceDock.

• Embedded build map (compiled into ckan.exe at build time)
• Remote build map (retrieved from network when updating registry)

These files need to be updated manually when a new game version is released. There is no automated validation associated with them, so a pull request isn't needed unless you want a manual reviewer to sanity check your changes before merging.