Better view of pending updates and revision history (was Cutting version 1.10)

[larsbarring]

In issue #343 Jonathan asks

Is there a reason why we should not release 1.10 with this change as soon as we've agreed it, and any others agreed since 1.9, and then start preparing 1.11 for release in the summer?

which prompted a couple of thoughts:

1. I was looking for what would be new or changed. But between the revision histories of v1.9 and draft v1.10 there are no changes. Is there another place where one could get an overview of which closed issues are covered by the draft version? --- If not, I think that it would be a useful addition, maybe as a subsection -- "New additions in this draft version" or similar -- after the ordinary revision history. But this should be a separate enhancement request.
2. I was hoping that the outstanding issue on temperature units would be resolved in the next version of the Conventions document. But I imagine there is still some work to be done before this happens, and if there are reasons to release 1.10 before so be it. There is always a new draft version to aim for :-)

---

After discussion, it was agreed to reformat the revision history with pull request #370, and to add tags and milestones for agreed issues, dormant issues and PRs implementing agreed issues. @JonathanGregory 18 Aug 2022.

[erget]

@davidhassell ping - thoughts here? (1) is a very good question - is there an easy way to generate such an overview in the absence of updates to the history section of the document? I imagine GitHub would be helpful, and it might be even easier if we use milestones that could be attached to PRs but AFAIK we're not doing that.

[JonathanGregory]

We could put headings in the history section (in history.adoc), starting a new one in each new release. Thus, the history section in the present draft would currently end with a title something like "Differences between 1.9 and 1.10", and there would be nothing there. Just to be clear, we could write "Nothing yet" underneath, and delete it in the subsequent changes! Does that make sense?

[JonathanGregory]

Separately, I would like to suggest that when we close issues in this repository which have been agreed to be implemented in the next release, we should add another label that indicates this e.g. "1.9" for all the ones added to the present version. Those new labels can all be the same colour, to conserve the visual spectrum. I think these labels might be useful when looking at the repo subsequently.

[erget]

@JonathanGregory I agree that a per-release entry in History would make sense.

What you propose regarding labels would work, although it might be simpler if we track them by pull requests. This is a common pattern in the software development world. This has been made easy for 1.9 as shown by this filter showing those PRs that were manually tagged as going into 1.9. If we were to do that again for 1.10 we would have such an overview, and the PRs would of course link back to their respective issues.

Barring that, this can be discovered by pulling up closed PRs and sorting by date, then checking what was merged into main between releases - that is however more laborious, so labeling the PRs pre-merge would be the most expedient in my view.

[zklaus]

For reference, in ESMValTool we use just the process that @erget described to generate the changelog using this script. We are considering replacing this with one of the many available standard solutions that do a similar thing.

[JonathanGregory]

@JonathanGregory I agree that a per-release entry in History would make sense.

OK. If others agree, this is something we could introduce in 1.10, and it might not be too hard to insert those headings for all the previous versions.

What you propose regarding labels would work, although it might be simpler if we track them by pull requests. ... This has been made easy for 1.9 as shown by this filter showing those PRs that were manually tagged as going into 1.9. ... Labeling the PRs pre-merge would be the most expedient in my view.

Thanks. That is neat. How do you tag the PRs in this way? I agree that it would be sensible to do that as soon as it is agreed that a PR will be merged at the next release.

However, this doesn't tag the issues, does it? Therefore I think it would still be useful to add a label to the issue once it's agreed to update the convention, for instance "Change agreed". This label would remain forever, and by following the link in the issue to its PR, tagged in the way you describe, you could find out which version it affected.

I would also propose a complementary label "No change agreed", to be applied to any issue which we close because it doesn't seem that it's going to reach a conclusion. Of course any closed issue could be reopened and the label removed. I feel that it's better to close issues than to leave them forever dormant. Do others agree, or am I being tempted by excessive tidiness?

[ethanrd]

I agree, per-release headers in History would be helpful.

@JonathanGregory - I like the idea of closing inactive issues after some period of dormancy and adding a "No change agreed" label to those issues. I also like the idea of adding a "Change agreed" label to issues as they are agreed (and PRs merged).

[davidhassell]

Hello all,

My (current) thoughts on the new release question: I'm not sure about cutting 1.10 to fix just this defect. Given that it can be fixed in the latest CF-1.10 draft, is that not sufficient to tide us over to the whenever CF-1.10 is released? A few years ago we agreed that one release, or perhaps two releases, per year was a good balance; which to me, at least, means that any extra release in the year should be reserved for either getting new functionality out to users with production time constraints, or else correcting a serious error. I'm not sure that this defect (important as it is!) adds new features, nor warrants the "serious" label.

I like the idea of per-release history entries, and "(No) change agreed" issue labels. I would find those very useful.

Daniel wrote:

Barring that, this can be discovered by pulling up closed PRs and sorting by date, then checking what was merged into main between releases - that is however more laborious, so labeling the PRs pre-merge would be the most expedient in my view.

That is exactly what I did when applying many of those milestones - and it was indeed laborious. Labelling them at merge-time would be a great addition to the workflow.

Setting a milestone on a PR (or issue) is very similar to setting a label - it's on the right hand panel just below where the label-setting feature is. I have just created a 1.10 milestone (via https://github.com/cf-convention/cf-conventions/milestones).

Thanks,
David

[erget]

@davidhassell agree with all your points. I also agree about the issue labels of changes being agreed or not, that would be easy to do and add value.

When we consider these process changes agreed, we should document them, e.g. in Rules.md or in the PR templates, in the form of a checklist. They're simple to do but would need easy presentation so that they don't get forgotten.

[JonathanGregory]

Dear @davidhassell

Thanks for explaining about milestones. As a test I have just attributed the closed issue about lossy compression by coordinate sampling to milestone 1.9. That is obvious when you open the issue, but you don't see it in the list of issues or when hovering on the issue, so a label saying "Change agreed" would be separately useful still. You can also filter the issues as Daniel showed for PRs. Filtering the closed issues for the 1.9 milestone now shows just the one I have tagged.

It's OK not to make a special release in order to fix this defect if we're sure there's not much danger of anyone coding Conventions as 1.8 instead of 1.9 without thinking about it.

Cheers

Jonathan

[erget]

We could always correct 1.9 using the procedure for errata so that 1.9 remains valid - leaving the error in 1.9 and minting a new release to correct it would be similar to deprecating 1.9, which would be new ground.

[davidhassell]

Dear Jonathan,

You can see the milestone, but it's easy to miss, as it's not formatted the same as a label:

The proposed "Change agreed" label is still a good idea, in addition to the milestone.

[zklaus]

Perhaps my previous comment was a bit obtuse. With regards to @erget's and @davidhassell's comments

Daniel wrote:

Barring that, this can be discovered by pulling up closed PRs and sorting by date, then checking what was merged into main between releases - that is however more laborious, so labeling the PRs pre-merge would be the most expedient in my view.

That is exactly what I did when applying many of those milestones - and it was indeed laborious. Labelling them at merge-time would be a great addition to the workflow.

I wanted to point out that this process can and should be automatized using the github api. It is really only a few lines of code (the changelog script I referenced above is less than 200 lines and includes formatting and filtering).

With this, the task won't be laborious anymore.

[larsbarring]

I am just quietly following all the good ideas and solutions that you github experts are coming up with. Many thanks for this!

While we are at it, here is another thought:

In the revision history I think that it would it be meaningful to have "subheadings" for each version of the conventions document together with its release data. The reason for this is that we are now and then discussing that in a file adhering to CF-1.X there might be a metadata construct that is defined/superseded/invalidated in a more recent version of the conventions, and that this is not a problem as it is known in which version a certain construct is introduced. E.g. something like

• Version 1.0, 28 October, 2003
  Initial release.
• Version 1.1, 17 January, 2008
  14 June 2004:
  Added the section called “Lambert azimuthal equal area”. the section called "Polar Stereographic" : Added latitude_of_projection_origin map parameter.
  1 July 2004:
  1/ Section 5.7, "Scalar Coordinate Variables" : Added note that use of scalar coordinate variables inhibits interoperability with COARDS conforming applications.
  2/ Example 5.13, "Multiple forecasts from a single analysis" : Added positive attribute to the scalar coordinate p500 to make it unambiguous that the pressure is a vertical coordinate value.
  ... ...
  17 January 2008:
  1/ Preface : Changed text to refer to rules of CF governance, and provisional status.
  2/ Chapter 4, Coordinate Types , Chapter 5, Coordinate Systems and Domain : Made changes regarding use of the axis attribute to identify horizontal coordinate variables.
  3/ Changed document version to 1.1.
• Version 1.2, 4 May, 2008
  4 May 2008:
  1/ Section 5.6, "Horizontal Coordinate Reference Systems, Grid Mappings, and Projections", Appendix F, Grid Mappings : Additions and revisions to CF grid mapping attributes to support the specification of coordinate reference system properties (Trac ticket New standard_name: atmosphere_mass_content_of_snow vocabularies#99).
  2/ Table 3.1, "Supported Units" : Corrected Prefix for Factor "1e-2" from "deci" to "centi". (Trac ticket New standard_name: mass_concentration_of_zooplankton_expressed_as_carbon_in_sea_water vocabularies#108).
  3/ Changed document version to 1.2.

and so on, but of course properly formatted. This might take some manual work, which should not delay releasing 1.10 before if need be.

[erget]

In a way this would move the history in the direction of being more akin to a classic change log spelling out the changes between releases, which I think would be a good thing. I imagine that the date of a change being merged is likely less important to most readers than the version in which it was released, and because we link back to the issues, if one needed to know the merge date of a specific change set, that would be possible.

[JonathanGregory]

Having let this go dormant six months ago, I have begun working on a PR to reformat the revision history as discussed in this issue. I will also summarise the proposals regarding labels. Jonathan

[JonathanGregory]

Dear all

Here is what I propose for the revision history. It's the same contents as before, but I have put it in a uniform format with each entry as "link to GitHub issue, trac ticket or date: text" (dates for the very earliest versions, before we had trac tickets), and I have turned it upside-down, so in future we will add new entries at the top of it. I think there are two advantages in having the most recent change at the top. (1) The top is what you see when you open the document, and it's the most recent changes you're usually interested in, rather than ancient history. (2) The title line for each version is both a heading for the changes it includes, which follow it in the document, and a marker in time for the release of the version i.e. later in time than the changes, because it appears above them in the document. In the AsciiDoc, to make it easier to edit, I have defined attributes :issues: and :pull-requests:, so the URL doesn't have to be coded explicitly each time.

Is this OK? If so, I will make a pull request to do it.

Jonathan

[erget]

Hi @JonathanGregory , this sounds very good - thanks for putting in the work!

[JonathanGregory]

Dear @davidhassell @erget @ethanrd @zklaus et al.

In the previous discussion I believe there was general agreement that the following would all be useful:

• When an issue is concluded with agreement to make a change, the issue should be tagged with Change agreed. This tag will make the imminent changes obvious in the list of issues. Since issues are closed once implemented, agreed changes will be visible with the default filter only if they have not yet been implemented.

• When an issue is concluded with agreement to make a change, the corresponding pull request will be attributed to the next version number (currently 1.10) as a milestone.

• Issues which have gone dormant should be tagged with No change agreed and closed after some period. There is nothing to prevent them being reopened subsequently, of course, and it's easy to make them visible in the list. I suggest that this should happen twelve months after the most recent update. (I have just revived this issue after six months, having not forgotten about it in the interim, so I think six months is too soon.)

I would further propose that the first two of these should be done for 1.10 but we need not do them for earlier versions, and the third will be done on an ongoing basis by anyone who has time and permission to modify the repos. I will spend some time on it myself.

If agreed, the above should be documented in the rules for making changes to CF conventions.

Best wishes

Jonathan

[erget]

Hi @JonathanGregory , I think this is a good idea and I also remember conversations that have proposed things along these lines. No need to do it for earlier versions of CF in my view.

Do you think that rules.md is the right place to document these? It sounds to me more like modalities of working with GitHub, in which case CONTRIBUTING.md might be a better home for these guidelines.

[JonathanGregory]

Dear Daniel @erget

Do you think that rules.md is the right place to document these? It sounds to me more like modalities of working with GitHub, in which case CONTRIBUTING.md might be a better home for these guidelines.

I am not sure. I think it's debatable. These two documents overlap somewhat in purpose. Could we merge them? In order to do that, we would have to put the rules for making enhancements and rules for correcting defects into the same file, along with the contents of CONTRIBUTING.

Cheers

Jonathan

[erget]

@JonathanGregory in fact I'd be very much in favour of merging them, as it would simplify things quite a bit. I'd also be willing to volunteer to support that one (I'm assuming you would too, so we could get the old team back together again! :) ). It'd have to be a bit of careful work, perhaps we could devote some hackathon time at the upcoming user conference to the topic if you're interested.

[JonathanGregory]

Yes, I could help. J

[erget]

Great, I've spawned #369 so I don't forget. I'll hold you to it ;)

[ethanrd]

This all sounds good to me. Thanks for reviving this issue.

[taylor13]

Upon review, I have not suggestions to make. I would thank those who have clearly spent considerable time thinking about this and working to implement it. It's a huge service in support of CF.

[JonathanGregory]

Dear all

Thanks for your contributions. I have prepared a pull request to reformat the revision history. Enough support has been expressed, so if there are no objections before 17th August it will be accepted on that day. (The rich diff is not much use for this PR because I turned the file upside-down, so it's completely different even though the contents are the same.)

I suggest the same deadline for comments on the decision to add Change agreed and No change agreed tags to issues, and to add version numbers as milestones to pull requests. Those don't involve a change to the convention, of course. They are a GitHub issue.

Cheers

Jonathan

[erget]

FYI while it's true that the rich diff isn't much use, you can view the updated file to get an idea of its integrity. I've had a look and it seems fine for me.

[JonathanGregory]

Ah, thank you! I was just wondering where to find that artifact. I know you had told me before. I've found it again now.

[davidhassell]

Hello,

Looks good, Jonathan, thanks.

Could we add the day of the month to the release dates? E.g. September 2021 would become 10 September 2021

[JonathanGregory]

Yes, certainly. It is only 1.7, 1.8 and 1.9 which currently don't show the day of the month, and you have just helpfully filled it in for 1.9. On which day in Feb 2020 was 1.8 released? I have just discovered from emails that 1.7 was released on 7 Sep 2017 (not Aug 2017). Jonathan

[erget]

You can see the dates when releases were minted on the releases page - 1.8 was 11 Feb 2020.

@davidhassell I take it tags, which have the same version numbers, are not considered equivalent to releases because of additional work in packaging, etc.? The tags have different dates than the releases.

[JonathanGregory]

Dear @davidhassell and @erget

Yes, certainly. It is only 1.7, 1.8 and 1.9 which currently don't show the day of the month, and you have just helpfully filled it in for 1.9. On which day in Feb 2020 was 1.8 released?
You can see the dates when releases were minted on the releases page - 1.8 was 11 Feb 2020.

I have added the release days for these three versions (now like all the others). I kept 7 Sep 2017 for 1.7, which was the day on which Jeff announced its release, although he subsequently updated it, as shown by the releases page (which I didn't know about - thanks).

Jonathan

[davidhassell]

Hi @erget,

I think that the tags should have the same date as the release, just to avoid any ambiguity, even if the content of the repo at the tag is identical to that that was released. We've not always been on top of this, but 1.9 got it right. I'm about to submit a PR to create a RELEASE.md that describes the release process - including making the tag on the release date.

@JonathanGregory,

Thanks for adding the dates!

[davidhassell]

Hello - I think that this is all good to go, So unless anyone has further comments, the start the 3-week countdown can be considered as 2022-07-28 (the last substantive comment), and we merge this on 2022-08-18, in time for CF-1.10.

Many thanks to Jonathan for putting the work in on this.

[JonathanGregory]

There have been no more comments on this issue (about the revision history in the CF conventions document). Please could someone merge PR #370?

[erget]

Sorry to come at the last minute - would it be ok to introduce a formatting change to the PR? I'd propose using a bulleted list rather than the current formatting, which makes each issue its own paragraph, and would be happy to implement if that's ok for the group. Should have proposed this earlier, mea culpa.

[davidhassell]

Fine by me.

[JonathanGregory]

OK. That doesn't change the content, so it could still be merged today, I think.

[erget]

Ok, done.