Add in a contributors document outlining the repo's process. #597
Conversation
This document is undoubtedly incomplete and can be iterated on. It represents, to the best of my knowledge, the *existing* process I have followed myself since the repository's inception, with only minor tweaks (back then lots of GitHub UI features didn't even exist!). Of course over the years it may not have been followed by everyone, nor even possibly by myself, but putting it here should hopefully make it clearer to everyone what the baseline is, in case we wish to make changes. There are some differences here from processes followed in other JSON Schema org repos -- whether this is an issue or not is of course constructively debatable.
There was a problem hiding this comment.
Points that I believe should be covered:
- effort should be taken to have at least one passing and one failing test for every schema that exposes the key functionality being tested (exceptions including of course schemas that are impossible to produce a failing result, e.g. annotation-only keywords)
- if the test is confusing to understand, and particularly for an existing test whose results are being changed, an explanation should be provided in a comment in the test (I believe the structure has been modified to allow for unlimited-length text fields such as this?)
- schemas and data should be as simple as possible while still exposing the proper functionality of tests - e.g. keywords that do not change the result should be removed
- this document should reference the README regarding the proper use of the remotes directory, the $schema keyword, etc
- a test being added to one draft version should be added (in as nearly identical a fashion as possible) to all other drafts to which the test would apply
|
Thanks. This document was meant to be more about process than a test style guide (which is #439) -- though I did start to get into some of that topic by adding the test modification section it seems, so happy to try to address some of those here. |
This comment was marked as off-topic.
This comment was marked as off-topic.
|
The request was to document the current process. We can certainly discuss changes to it but what I've written down is what's been done until now. GitHub notifications are a way, and maybe one that works well for you personally, but not the only one -- as I say though, we can discuss changes certainly. |
|
@karenetheridge added those, thanks. Have another look. |
Hopefully this was obvious regardless.
|
Thanks all -- going to merge, but will mention again step 1 was to just write this down, so certainly now if anyone feels strongly about changing things feel free to bring it up in a discussion or issue or whatever. |
|
Oh -- in exchange I'll also ask that if something comes up in a PR that seems like it belongs in here (because we forgot to add it, say) please make that note on said future PR when it happens! |
This document is undoubtedly incomplete and can be iterated on.
It represents, to the best of my knowledge, the existing process I have followed myself since the repository's inception, with only minor tweaks (back then lots of GitHub UI features didn't even exist!).
Of course over the years it may not have been followed by everyone, nor even possibly by myself, but putting it here should hopefully make it clearer to everyone what the baseline is, in case we wish to make changes.
There are some differences here from processes followed in other JSON Schema org repos -- whether this is an issue or not is of course constructively debatable.