New CF vocabularies repository - available 30th July 2024

[japamment]

At the June meeting of the CF committee it was agreed to create a new repository https://github.com/cf-convention/vocabularies within the CF GitHub organisation. The purpose is to have a clearly labelled repo which collects together all discussions and resources related to the CF controlled vocabularies (standard names, area types and standardized regions). From 12:00 UTC on Tuesday 30th July, if you wish to open a new issue to propose changes to any of the vocabularies please do so in the vocabularies repo. Until then, please continue to open new issues in the discuss repo in the usual way.

In preparation for this change, the vocabularies team (@feggleton @efisher008 and myself) will migrate all existing vocabulary related issues (both open and closed) to the new repo on Monday 29th July. Any labels applied to issues in the discuss repo will be carried over to the new repo and the conversations within the issues will continue in their new location without interruption.

No issues will be lost as a result of this work. To allow time for everyone to get used to the change we'll continue to check the discuss repo periodically over the next few weeks and manually migrate any vocabularies issues that are opened there.

I will post again once the initial migration is complete.

Alison

[DocOtak]

Is there a utility provided by an independent repository and issue tracker that is not provided by having an independent category in the CF discussions? Granted I'm not intimate with the work flow, my concern is more of how many entry points participating in CF seem to have, with #335 it seems that a single point of entry for participation was about to happen. For many folks I interact with, CF is the standard names and they don't talk about much more than that.

[JonathanGregory]

Dear Andrew @DocOtak

We discussed this in the committee meeting as well. Another action we decided upon is better signposting. We should improve the READMEs of the repos, and provide one for the CF organisation as a whole. We can also add more signposts on the website. An advantage of #335 is that there will be just one place to go (Discussions) if you're not sure where to go! But for standard names, people generally know they want to propose new ones, without needing Discussions. What is the first point of call in the CF website/GitHub for your friends who think CF is just standard names?

Best wishes

Jonathan

[DocOtak]

Re the folks who think CF is mostly the standard names, I don't think they make it past looking at the data files themselves (with e.g. ncdump). I suspect that for many people, requesting standard names are their point of entry into active participation in CF rather than just as a user. This was certainly the case for me.

When I first thought I might get involved with CF, it was the old mailing list. I joined it and just watched and learn: how are standard names proposed? how are changes to the conventions done? how are questions asked? what are the common questions? I probably waited over a year before I actually sent in my own questions. But I could see the whole thing working. Now however, things are spread across these discussions, individual issues in the old discuss repo, issues in the cf conventions document repo, issues in the website repo, pull requests in both the conventions document and website repos. Thats at around 6 places conversations can happen all of which are opt in for non members of the github organization (in any capacity not just e.g. committee members) as members are often subscribed to new repository events. This feels complex not because it needs to be, but because we have made it that way. Having a separate vocab discussion/request location creates a pretty strong barrier between vocabularies and everything else for participating, especially passive participation where folks just watch and look for anything relevant to them. It would effectively hide the standard name proposal process and discussions from people who are not already involved in those discussions.

An organizational level readme would be excellent, but I think the need for more or better "signposting¹" should be treated with suspicion as smell that we aren't using or utilizing the tools provided by GitHub in an efficient way. I'm not advocating that there should be no guidance or direction given (i.e. there should be signposting). but that should just be one big button that says "Participate" and it sends you to the organizational level discussions board. We should rely on built in GitHub features as much as possible to guide folks to the right place and github itself guides you to discussions quite a bit when they exist (there is a sidebar showing the most recent ones when looking at the CF organization landing page). Then when creating a new discussion, it will guide you to the correct topics if we have them. Having a separate vocabularies discussion location just feels like reinventing the already built in GitHub Discussions Categories feature to me.

To be clear, I'm trying to advocate for simplicity and some consolidation of the number of locations discussions occur. A separate repository for the vocabulary assets themselves is good and should be done. I also realize that many of the policies and procedures were made before many of the project management features GitHub provides even existed.

Footnotes

1. signposting is a new word/phrase for me. ↩

[pvanlaake]

But then again, for "the folks who think CF is mostly the standard names" wouldn't it be easier and cleaner to find everything on standard names in one location and nothing else but standard names? Those same folks might also not be very proficient in using GitHub to begin with.

[DocOtak]

My impression is that GitHub is trying to position the discussion feature as the "non developer" conversation location or starting point. One of the benefits I think to utilizing the organizational level discussions is that it is above the "repositories" so there is no need to understand those as a concept.

To provide an isolated view of nothing else but standard names you can link directly to discussion categories, perhaps in the new/improved readmes. For example, a link directly to our Announcements category which only shows announcements. When you click on the green "New Discussion" button, it has the current category already selected. So if we had a Standard Names (or Vocabularies) category, we could link directly to it and get all the benefits of being able to provide an isolated view of those discussions.

[JonathanGregory]

@DocOtak The committee's proposal in #335 is that general discussions will take place only in the organisation-level Discussion forum. New issues in the new vocabularies repo will be only for proposing changes to vocabulary, especially standard names. Usually the refinement of proposals involves some discussion too, but that is specific to the issue. It's more like commenting on the exact wording of a convention change. The Discussion forum is the place that any newcomer should go to participate, if they are not already familiar with how to make a proposal. Announcements, questions and general discussions about standard names and other vocabulary will take place in Discussions (like this announcement). You can produce a filtered view of Discussions relevant to standard names like this. If you'd like to continue this thread, I think it would be better to move to #335, because Alison opened the present Discussion as an announcement.

[japamment]

Dear CF community,

@feggleton @efisher008

The migration of all vocabulary related issues from the discuss repo to the vocabularies repo has been completed successfully. Both open and closed issues have been moved. All labels have been transferred along with the issues and will continue to apply as before.

From now on, if you wish to open a new issue to propose changes to any of the vocabularies please do so at https://github.com/cf-convention/vocabularies/issues.

An unavoidable consequence of the migration is that numbering of existing issues has changed. This is because numbering in a new repo starts at #1. However, any links to other issues that appeared in comments in the discuss repo have been automatically preserved as part of the transfer process. They now point to the new number of the linked issue and will still work as expected.

The default way of sorting GitHub issues is to display the most recently created first, so newly created issues appear on page 1 of the listing and older ones on subsequent pages. If you wish to change this ordering you can do so using the "Sort" drop down menu at the top right of the listing.

Thank you for your patience while the migration was taking place and apologies if automated messages caused a lot of traffic in email inboxes yesterday.

Best wishes,
Alison

[JonathanGregory]

Thank you, standard names team (@japamment @feggleton @efisher008), for doing this helpful work.