Add a **Release highlight** page #429
Comments
larsbarring
added
the
enhancement
|
Dear @larsbarring Rather than introduce new categories, could we not make use of the categorisation we already have, between Best wishes Jonathan |
|
Dear @JonathanGregory I thought a about this for a while, but looking at the list of issues that have been closed now with 1.11 I think these two categories are not fine-grained enough. While I do admit tht ther eisa degree of value judgement and sa few boundary cases on the list above, I think that we can agree that most of the ones stricken over are not of interest to the readers/users, .e.g.
just to pick two random ones. These do not need to be mentioned at all (I am not sure that all such are labelled Then we have a middle category, which are the ones that I tentatively called "Clarifications". These are relevant to briefly highlight because they do provide a clarification in relation to what has been discussed,or asked, or otherwise influence users' understanding and interpretation of the conventions. E.g. these ones:
And then there are the (usually few) enhancements that add important new features or otherwise have more far-reaching consequences that should be highlighted. So, I do think that with three categories we can substantially improve this. Moreover, I understand that github have more advanced mechanisms for supporting and automating categorising issues/PRs into different types thus helping out with this. But I do not have any deeper insights in how it works. |
|
Dear @larsbarring I would say that the two struck-out examples you have picked could or should have been Enhancements are changes to the substance of the convention. They may affect what users do, whether writers or readers of data. Enhancement issues require explicit support to be agreed. Defects are mistakes in the text or formatting, or things which have been stated wrongly (inconsistent with the agreed intention) or unclearly. Users don't have to change what they are doing, but existing defects might have made it hard for them to understand the convention text or decide what to do, so they are worth rectifying. Defect issues are agreed by default, if no-one objects. Clarifications could fall into either category. I think it would be helpful, and should serve your aim, if we consider carefully which category to choose for each one. Bearing in mind that Best wishes Jonathan |
|
Dear Jonathan, I realise that did not express the idea I had in mind very well (rather the opposite I am afraid). The intention was not to focus on issue categories, but rather to highlight the essence of the new release in the main webpage of cfconventions.org (hence the issue title and having the issue in this repo). What I intended is something like these two examples Mockup 1: Conventions: Latest release (1.11) HTML PDF Highlights • Working draft HTML PDF Vocabularies: Standard names • Area types • Standardized regions where the "Highlights" is a link to a summary of the major new elements in the release. Mockup 2: Conventions: Latest release (1.11) HTML PDF • Working draft HTML PDF Vocabularies: Standard names • Area types • Standardized regions And the same for the "Release Highlight" And the link points to a separate web page or, perhaps preferably, to a discuss/#issue that announces the new release. Something like this ("zero-order-draft"): Release of CF-1.11A brief text as introduction, perhaps something like: Highlights
|
|
Dear @larsbarring Sorry I missed your point. I probably read the title of the issue, but forgot about it once I started reading your categorisation of the revisions included in 1.11! I agree that a web page of release notes would be useful, highlighting the changes which users should be made aware of. Not to be deterred from my theme, though (!), I would suggest that it's the Best wishses Jonathan |
The just released version 1.11 includes 33 changes according to the Revision history (and even more, 57, if one looks at the github release page). But a majority are technical/language fixes or improvements of little interest to users of the conventions document. In the worst case important enhancements or changes may go unnoticed.
From my very own tentative assessment about half of the entries in the Revision history are of little interest to the reader/user (other than perhaps a vague feeling that "things are now clearer more easy to understand" :-) ) :
The remaining ones could perhaps be divided into something like
"Major enhancements and new features"
units_metadataattribute and clarify some other aspects of units"Clarifications" (some of the listed items may not qualify?)
The "Major enhancements and new features" items should then be described with a few sentences that also refer to the relevant sections in the document. Similarly, the "Clarifications" items should be explained with a sentence, if possible lumping together related items, like for example the ones related to CRS/map projections (Polar Stereographic, rotated Mercator, and spherical Earth).
The text was updated successfully, but these errors were encountered: