Decentralized meta and links object documentation (Issue #136) #176
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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.
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
requested review from
rogpers-ericsson,
e-backmark-ericsson,
xvinosi-github,
l-ohlen-ericsson,
erobged and
ebopalm
| __Required:__ No | ||
| __Legal targets:__ [EiffelTestExecutionRecipeCollectionCreatedEvent](../eiffel-vocabulary/EiffelTestExecutionRecipeCollectionCreatedEvent.md) | ||
| __Multiple allowed:__ No | ||
| __Description:__ When declared in an EiffelTestSuiteStartedEvent, this link signifies that the test suite groups all test case executions resulting from the [EiffelTestExecutionRecipeCollectionCreatedEvent](../eiffel-vocabulary/EiffelTestExecutionRecipeCollectionCreatedEvent.md). |
There was a problem hiding this comment.
This when statement is a bit reduntant now, since the description is in the EiffelTestSuiteStartedEvent
erobged
reviewed
Feb 16, 2018
As proposed by reviewer in the PR thread, rephrased the description of TERC link in EiffelTestSuiteStartedEvent to remove redundant self-referral to the event type.
This was referenced Feb 19, 2018
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Applicable Issues
Issue #136
Description of the Change
This PR moves the documentation of the meta object and all link types into the respective event documentations. The reasons for this are outlined in Issue #136. Essentially, documenting these objects (although common) centrally and separately from the individual events is incompatible with the per-event versioning scheme.
This is exemplified by Issue #170, which would require an update of the link-object and a stepping of all individual event versions. The problem is that there is no way to document which version of which event follows which links object syntax, unless that information is included in the documentation of the event itself. Simply put, the documentation of each event type must be self-contained.
The link and meta documentation was consciously not added in alphabetical order or following the event structure. I added ##Links after ##Data members, and ##Meta members last, because I believe this should reflect the most common order of interest (##Meta should just be boilerplate, so that can go at the end). I also listed the link types in order of presumed interest (e.g. all the optional common link types at the bottom).
Alternate Designs
Keeping it as it is is conceivable, but highly impractical. It would require listing event versions from the central documentation location. This would make for poor readability and poor overview. Arguably, even without the versioning problem, this change makes it easier to see which link types apply to each event type.
You could keep the documentation centralized, but in multiple versions, and then link the appropriate version from the event type documentation. I doubt this improves anything for the reader, though. It may be easier for maintainers, but on the other hand, there's always find, xargs and sed :)
Benefits
This PR allows us to make changes to the links and meta objects. Specifically, it is a prerequisite for addressing Issue #170.
Possible Drawbacks
More copy-pasted boilerplate documentation.
Sign-off
Developer's Certificate of Origin 1.1
By making a contribution to this project, I certify that:
(a) The contribution was created in whole or in part by me and I
have the right to submit it under the open source license
indicated in the file; or
(b) The contribution is based upon previous work that, to the best
of my knowledge, is covered under an appropriate open source
license and I have the right under that license to submit that
work with modifications, whether created in whole or in part
by me, under the same open source license (unless I am
permitted to submit under a different license), as indicated
in the file; or
(c) The contribution was provided directly to me by some other
person who certified (a), (b) or (c) and I have not modified
it.
(d) I understand and agree that this project and the contribution
are public and that a record of the contribution (including all
personal information I submit with it, including my sign-off) is
maintained indefinitely and may be redistributed consistent with
this project or the open source license(s) involved.
Signed-off-by: Daniel Ståhl, daniel.stahl@ericsson.com