How to Wrangle Metadata for KSP1

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 "KSP2" checkbox at the top to view only KSP1 mods)
• Subscribe to notifications from both metadata repos
  • https://github.com/KSP-CKAN/NetKAN (netkans, the templates that CKAN uses to find releases and fills in)
  • https://github.com/KSP-CKAN/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 master.

Incoming pull requests accumulate here: https://github.com/KSP-CKAN/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 add 1.10 1.11 1.12 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 master 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/NetKAN/tree/master/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
• You can convert old JSON netkans to YAML with https://codebeautify.org/json-to-yaml
• 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
• 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.