build command: package a README.md, from /README.md, or from a sysand.toml configurable source

[simonas-drauksas-sensmetry]

User story

As a systems engineer developing SysML v2 packages
I want to include a README with my package
So that the end users of my package can better understand the purpose and usage of my package.

Background

The current KerML clause 10.3 specifies that the .kpar file archive can only have the following files (and nothing else):

• Project files in one of the following model interchange formats: textual notation (.kerml or .sysml), .json, or .xmi
• .project.json
• .meta.json

The exact quote from the spec:

A project interchange file is contains a single project serialized as a set of model interchange files, archived using the ZIP format [ZIP]. The archive shall contain a model interchange file for each of the root namespaces in the project, each formatted in one of the formats listed in 10.2. In addition, the archive shall contain, at its top level, exactly one file named .project.json and exactly one file named .meta.json. A KerML project interchange file shall have the file extension .kpar (KerML Project Archive).

Other package managers

• Python's PyPI allows and encourages READMEs in plain text, Markdown, or reStructuredText
• npm allows and encourages READMEs in Markdown
• NuGet allows READMEs in Markdown
• Visual Studio Code Extension Marketplace allows and encourages READMEs in Markdown

Tasks

• Raise this issue at OMG
• Develop a Proof-of-Concept that packages a README.md file into the .kpar
• Develop a way for sysand.org public package index to automatically render the included README.md file on the package's page. (task for outside of this repository)

[tilowiklundSensmetry]

My reading of the spec is not that the archive cannot contain anything else. It simply requires certain things to be present.

[consideRatio]

My understanding is that we can simply move ahead, and give special treatment to README.md if we like, such as bundling it when building a .kpar.

The index needs a way to provide people with information about the package, especially since the package just have a "website" and not more details like official docs / source code / etc links. Due to that, a readme file is even more important.

A decision about this, influences the client->index publishing API, where we could either accept just a .kpar, or have a README.md datablob be sent along the side of the .kpar. I think the sensible approach is to have the README.md be part of the .kpar.

Suggestion

• We act without further ado, and bundle a project root located README.md with sysand built .kpar archives, and we make the client->index publishing API simpler by not needing to accept README.md information along the side of the .kpar archive.
• We determine if there is some concrete non-blocking OMG follow up we'd like to pursue

@simonas-drauksas-sensmetry @tilowiklundSensmetry @andrius-puksta-sensmetry wdyt: OK to proceed and update the build command to add a project-root/README.md into the .kpar archive?

[andrius-puksta-sensmetry]

OK to proceed and update the build command to add a project-root/README.md into the .kpar archive?

Fine by me. Probably should log::info if readme is included to not surprise users.

[simonas-drauksas-sensmetry]

Maybe have an option in sysand.toml (or somewhere) to overwrite the README file name? E.g. if they want to have README.md for their internal repo, but PUBLIC_README.md for the readme that is bundled with KPAR? In the KPAR, the file would still be called "README" in the end

[consideRatio]

This is quite isolated and relevant to get done to make sysand-index more production ready as well, so I'll work it now.