When making changes to the features specification, most notably when adding new features, questions arise for the author of those changes around what they should document and what is outside of scope.
We need a canonical source of truth that authors can be pointed towards when considering scope of the specification points that they are writing.
What?
Work under this issue will most likely end up as additions to our Features Specification guidance. These additions should include things which are within scope of the spec as well as things which we are agreed fall outside of scope (even if, in the past, they have been included).
Triggered by this code review comment on a spec change, where @paddybyers states:
I think we should generally avoid adding statements that say "A test must exist ....".
Which is something many of us implicitly understand, however historically Ably has lots of statements to this effect that have already been included in the spec.. Phrasings include "a test should exist", "a test must exist", "a test should assert", "an explicit test", "you should have a test", "should have test coverage" and "test coverage should be provided".
The spec is already a very heavy document and conflating test requirements into it adds noise and at times makes it difficult to ascertain a single source of truth for any given SDK requirement.
Why?
When making changes to the features specification, most notably when adding new features, questions arise for the author of those changes around what they should document and what is outside of scope.
We need a canonical source of truth that authors can be pointed towards when considering scope of the specification points that they are writing.
What?
Work under this issue will most likely end up as additions to our Features Specification guidance. These additions should include things which are within scope of the spec as well as things which we are agreed fall outside of scope (even if, in the past, they have been included).
Taking into account the notes around Future Direction captured in
ably-common.See also: https://github.com/ably/specification/issues/1
Example: Specifying Test Requirements
Triggered by this code review comment on a spec change, where @paddybyers states:
Which is something many of us implicitly understand, however historically Ably has lots of statements to this effect that have already been included in the spec.. Phrasings include "a test should exist", "a test must exist", "a test should assert", "an explicit test", "you should have a test", "should have test coverage" and "test coverage should be provided".
The spec is already a very heavy document and conflating test requirements into it adds noise and at times makes it difficult to ascertain a single source of truth for any given SDK requirement.