PicoPackage

This is a scheme for sharing text content, often source code, that's too small to be a language package ( Gem in Ruby, Package in Python, Create in Rust, Module in Perl or Go) but used frequently enough that copy and pasting between projects is painful. It is used to track a single file of text, allowing you to update it centrally for distribution, hosted as a file or a URL.

Taking the concept of front matter from static site generaters, we add a commented block of metadata encoded with Yaml, which will be parsed by the picopackage tools.

Hosting goals

Ideally, code can be hosted anywhere, but it'd be great to specifically support Github Gists.

Audience

It's perfectly acceptable to use Picopackage for private code, for personal or organisational use. It's perfectly acceptable to package code or configuration or data for public consumption.

Dependency Management

None - currently.

Testing

Ideally, there'll be a test method or link to a test file.

Secure

SHA hashes to ensure content hasn't changed. SigStore to validate the author

Metadata

Using comments, we'll include the following attributes

Required Metadata

url: Link to a the human readble version.
file_name: name of the file, otherwise guessed from the url
version: the version of this file.
content_checksum: A sha256 hash of the file contents, excluding the front matter.
content_timestamp: Timestamp for the content, formatted as RFC1123.

Optional Metadata

licence: souce code licence
source_url: Optionally link to the latest version of this file if url isn't parsable.

Future consideration

Public Key signature, like RubyGems

signature: A Base 64 Signature
public_key: The public key component for signature verification

Sigstore

sigstore: attributes for sigstore including :signature, :rekor_log_id, rekor_entry - for future

Example

# @META_START
# home_url: https://gist.github.com/dkam/525ac4177964549ee2f2ca7febd03eea$0
# version: 1.0.0
# source_url: https://gist.github.com/dkam/525ac4177964549ee2f2ca7febd03eea/raw/
# test_method: test_me
# licence: MIT
# content_checksum: sha256:d7a8fbb307d7809469ca9abcb0082e4f8d5651e46d3cdb762d02d0bf37c9e592
# signature: base64:MEUCIQCjRx4RQvXxhPqvqyOB8FQtHGLuoA3pG4qBbNV4LGJTGAIgbZxXD9UFWqLsT+GZYs1DMqVXf6Lj2Dh8BM3wXJJ4Sxs=
# public_key: -----BEGIN PUBLIC KEY-----\nMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE7DxL6Mj/Bc9VhgKrWYItPqNxYPQ4\nzrVXXaHJWKNEHgSBgFH1AiJJ0cD3vFKkWuuhgnV8JdP/RXs4+G3oHqgQTA==\n-----END PUBLIC KEY-----
# @META_END

2.5 KiB Raw Permalink Blame History