Decentralize meta and links documentation, and validate links #136
Comments
|
Will make the effort to create a PR to this effect. This has been made more relevant by the work ongoing in operations-extension and also #170 |
d-stahl-ericsson
added a commit
to d-stahl-ericsson/eiffel
that referenced
this issue
Feb 15, 2018
As described in issue eiffel-community#136, because of the per-event versioning scheme it is untenable to keep link type documentation central and separate from event types. When link types are changed, this constitutes an event version change. Therefore, the link types of each event type must be documented each respective event type documentation. the-links-object.md has been preserved, but only contains general information. The repository has been searched for occurrences of the-links-object.md and has been updated accordingly.
d-stahl-ericsson
added a commit
to d-stahl-ericsson/eiffel
that referenced
this issue
Feb 15, 2018
As described by Issue eiffel-community#136, the per-event versioning scheme requires that even common syntax be described on a per-event basis, lest the documentation and/or versioning break down. This commit moves the meta object documentation into the documentation of each respective event.
d-stahl-ericsson
added a commit
that referenced
this issue
Feb 19, 2018
As described in issue #136, because of the per-event versioning scheme it is untenable to keep link type documentation central and separate from event types. When link types are changed, this constitutes an event version change. Therefore, the link types of each event type must be documented each respective event type documentation. the-links-object.md has been preserved, but only contains general information. The repository has been searched for occurrences of the-links-object.md and has been updated accordingly. As described by Issue #136, the per-event versioning scheme requires that even common syntax be described on a per-event basis, lest the documentation and/or versioning break down. This commit moves the meta object documentation into the documentation of each respective event.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Documentation of meta and links should be done on a per-event basis. This will result in a fair bit of "boilerplate documentation", but given the per-event versioning of the protocol I think it's the only reasonable approach. Since presumably two separate event types/versions can have separate definitions of these objects, common definition will require dependency management and a considerable risk of inconsistency once these begin to diverge.
Following that, we should use the schemas to validate required items in the links list. We can't forbid additional link types, however, since that would prevent extending the protocol.
The text was updated successfully, but these errors were encountered: