add notes about making minor model changes #1537
Conversation
|
Staging build running now |
| Major or minor release? | ||
| ^^^^^^^^^^^^^^^^^^^^^^^ | ||
|
|
||
| A minor release of the OME model schema may suffice for changes like |
There was a problem hiding this comment.
Thanks a lot for that. As we are using may/must, I would propose to add the usual reference to RFC 2119 for the exact interpretation of the terms.
There was a problem hiding this comment.
git grep 2119 in ome-documentation gives me zilch; could you point me to an example of what I should say? Do you want the all-caps style too?
There was a problem hiding this comment.
Yes I do not think we have used it extensively across our documentation yet. An example of usage is at the top of ome/design#55.
Happy to discuss if this is still premature but we could certainly promote a more general usage /cc @hflynn @rleigh-codelibre
There was a problem hiding this comment.
I am currently working on a BF docs PR which will also reference it so happy to have this become more widely used (it isn't referenced as yet but I think Roger has already used it for the version requirements page wording - I certainly have https://trello.com/c/HSPvUKRK/474-best-practice-for-imperatives-key-word-usage on the docs board after he pointed it out to me)
There was a problem hiding this comment.
I'm not sure they add much in this case (English "must" is already unequivocal even without the emphasis I added); I also wonder if those definitions should be a more general intro to the docs than repeated at the top of most pages, then the pages can just put them in some special style (like RFCs' all-caps)? Could certainly add here if seems warranted but I think this might be worth a deeper think beyond this PR.
There was a problem hiding this comment.
Oh dear, didn't mean to open a can of worms :) Having this sentence as part of the introduction of the documentation would certainly be a sensible option especially if we reuse them more. Happy to use @hflynn's Trello card to channel this discussion.
|
Overall this reads well and describes most of the steps we have been through for 2016-06 version 2. Only minor question is whether adding a |
|
These changes look good and certainly make sense and cover any minor release differences that I can think of. It all reads well and is easy enough to understand from my perspective anyway. |
Extends http://www.openmicroscopy.org/site/support/contributing-staging/data-model-schema.html to clarify how to adjust the process for "minor" model releases.