~whereswaldon/arbor-dev#155: 
Write a spec for the twig extensions defined in forest-ex

forest-ex has defined some semantics for certain twig metadata keys that we are starting to respect within our infrastructure. We should document and publish a specification of these extensions to aid others in building compatible arbor software.

Status
RESOLVED IMPLEMENTED
Submitter
~whereswaldon
Assigned to
No-one
Submitted
2 years ago
Updated
1 year, 8 months ago
Labels
2 Coffees bounty claimed documentation forest-ex specification

~athorp96 1 year, 9 months ago

I claim this

~athorp96 1 year, 9 months ago

There are a couple different ways we can approach twig specs. For maintainability I think we should standardize them. One solution would be to include a spec.toml (or some other format) which would describe:

  1. The purpose of the metadata
  2. The name (key)
  3. The version(s)
  4. The binary data attached, per version. e.g. data type, use for portions of bits, etc.

For example, for Active Status:

title = "Active Status"
description = "Indicates whether or not a user is or is not online. Ideally sent as 'active' when a user connects to a forest, with the client sending an 'inactive' message upon exit. Should be used in combination with expiration in case of unclean exits. Also intended to be invisible."
key-name = "activity"

[version.1.data]
type = "string"
description = "A stringified integer, '0' or '1', representing 'Active' or 'Inactive', respectively."

I'm open to suggestions about file format and structure, of course.

One thing to consider here is discoverability. We should make sure we catalog the different twig extensions in a central file, perhaps inside of forest-go/twig/extensions.txt which enumerates and links to extensions specs.

Please let me know your thoughts

~whereswaldon 1 year, 9 months ago

I see this as a multilayered problem. There's a set of metadata with very specific semantics (invisible, expiry, etc), and a set of conventions for how clients should combine these attributes to accomplish useful things.

I have no objection to using a structured text format for the various specs, though I'm not yet certain what we get beyond standardization from that. Perhaps we could generate code from that in the future? Anyway, TOML seems like a fine approach there.

Thanks for posting, as your questions helped me clarify my thinking on this. I'd like to see two things:

  • a structured text document describing each metadata field
  • a markdown document (or set of documents) describing conventions for their use. For instance, one of these would be "User activity indicators", and would describe using the expiry, invisible, and active-status metadatas together to announce the {on,off}line status of a user, as well as recommendations for when such messages should be created.

~athorp96 does that make sense to you?

~athorp96 1 year, 9 months ago

That does make sense. I was having trouble considering how to best represent both the usage as well as the specification. I agree that these are separate (though related) problems and I believe I was just conflating them. Pulling from the previous example, the title and description field would be pulled into a README.md which would also include a "usage" section.

Readme:

// `/forest-ex/active-status/README.md`
# Active Status
Twig metadata which indicates whether or not a user is or is not online.
Ideally sent as 'active' when a user connects to a forest, with the client
sending an 'inactive' message upon exit.  Field specification in
[spec.toml](/forest-ex/active-status/spec.toml).

## Usage
Should be used in combination with expiration in case of unclean exits.
Also intended to be invisible. yada yadda

Accompanying spec:

# /forest-ex/active-status/spec.toml
key-name = "activity"

[version.1.data]
type = "string"
description = "A stringified integer, '0' or '1', representing 'Active' or 'Inactive', respectively."

~whereswaldon 1 year, 9 months ago

I think this formatting looks good, but these should go in this directory (or a subdirectory).

~athorp96 1 year, 9 months ago

I was writing that I think it is obfuscating to separate the spec from the module, however it occurred to me that it’s really separating the spec from the implementation, which is ultimately a good thing, as it promotes extensibility. I think it’s important to call that out as a design decision. We should still provide at least a link to the spec in the module though. Perhaps in a README?

~athorp96 1 year, 9 months ago

I was writing that I think it is obfuscating to separate the spec from the module, however it occurred to me that it’s really separating the spec from the implementation, which is ultimately a good thing, as it promotes extensibility. I think it’s important to call that out as a design decision. We should still provide at least a link to the spec in the module though. Perhaps in a README?

~athorp96 1 year, 9 months ago

I was writing that I think it is obfuscating to separate the spec from the module, however it occurred to me that it’s really separating the spec from the implementation, which is ultimately a good thing, as it promotes extensibility. I think it’s important to call that out as a design decision. We should still provide at least a link to the spec in the module though. Perhaps in a README?

~whereswaldon 1 year, 9 months ago

Absolutely link to the spec! Link to it from everywhere! But yes, we should keep the spec separate so that other implementations don't need to dig through our golang codebase to find them.

~athorp96 1 year, 9 months ago

I messed up and somehow had upstream set as my default push remote. I have made added a twig-extensions directory and added the two specifications for active-status and expiration[1]. Please let me know if you have any feedback. All subsequent commits will be in the form of a patch

[1] https://git.sr.ht/~whereswaldon/arborchat/tree/main/item/specifications/twig-extensions

~whereswaldon 1 year, 9 months ago

I've made some minor edits. Thanks for working on this!

~whereswaldon 1 year, 8 months ago

~athorp96 What's the status on this?

~whereswaldon 1 year, 8 months ago

I believe this is complete with the acceptance of https://lists.sr.ht/~whereswaldon/arbor-dev/patches/22614

~athorp96 1 year, 8 months ago*

Woohoo! Feels weird collecting a coffee for the first time :P I'd like to explore more libre/OSS options but for now I'm on Paypal. The email I have for my PayPal is ~redacted~.

~whereswaldon REPORTED IMPLEMENTED 1 year, 8 months ago

The Coffees are sent!

~athorp96 1 year, 8 months ago

Thank you!

~athorp96 1 year, 8 months ago

Thank you!

Register here or Log in to comment, or comment via email.