I've been thinking through this and I first want to make sure I understand the intended purpose.
By definition metadata isn't (or shouldn't be) necessary to have a working/compiling package and should be entirely optional. A
README usually contains any additional info in terms of a human-readable format. Since that format is supported as-is by most git-hosts as well as Xcode, it seems pointless to duplicate that information.
I think that narrows down the purpose to automated parsing and indexing. Is there another use case I should be considering?
My main concern around putting this info in the manifest is it would chain any metadata changes to SPM/Swift evolution and versioning. If an indexer gets popular they will likely want/need to add additional fields without going through this process. I also would expect them to want additional metadata specific to their use case that wouldn't belong in the manifest. This could be supported by an
other option that allows raw entry, but that kind of defeats the purpose of a manifest standard.
In that context a separate file would probably be better and preferably in a format that allows non-standard fields. However at that point I'm unsure what the utility is for having an official standard. Especially before anything needing the metadata has taken off.
Would another option be to, rather than define a standard, support linking metadata files?
metadata: [ .readme(path: "README.md"), .license(path: "LICENSE"), .other(path: "SPIMetadata.yml"), ]
This has some advantages
- Concisely referring to additional info without mucking up the manifest
- Remove some of the "magic" a lot of these files currently have
- Avoids any localization issues
- Avoids format wars
- Allows standards to emerge and evolve naturally
- Allows private or non-standard uses
It would also codifiy existing emergent standards while allowing more flexibility
metadata: [ .readme("instructions/SPM_README.md"), // Allows path flexibility and creating an SPM specific README .license(), // Path could default to "LICENSE" ]
And if standards are established (or existing standards adopted), it could easily be extended to indicate a standard without requiring that standard to be defined within SPM.
metadata: [ .license(type: .mit2), // path defaults to "LICENSE" .other(path: "metadata/SPIMetadata.yml", type: .spi), .other(path: "metadata/ssc.json", type: .softwareSourceCode), ]