Labels in the conventions repo

[JonathanGregory]

28th Aug 2024. I am changing the title from "possible use of GitHub Discussions in the CF org, dormant and question labels in the conventions repo to Labels in the conventions repo.

As proposed originally, style and typo have been abolished. The question of question and dormant labels remain open in this issue.

Dear all

In issue 137 of the discuss repo we have discussed and agreed some changes to labels in that repo. I have just modified some of the descriptions of labels in this repo to make them the same as or analogous to the ones we have in discuss, and I've also changed a couple of colours to make them the same for corresponding labels.

I have introduced a frequently asked question label, the same in the discuss repo, to mark questions that should be considered for the FAQ. (Work needs to be done to expand the FAQ.)

Here's a question about questions: Should we have questions (about conventions) in this repo at all, or should such questions be asked in the discuss repo? If the latter, we should clarify this intention, and we won't need question or frequently asked question labels in this repo.

Can we abolish the typo label, currently distinct from defect? A typo is a kind of defect, and should be corrected by a defect issue.

Can we abolish the style label (use for issues concerning formatting or document syntax)? I would suggest that changing the style ought to be an enhancement if it refers to the entire document, or a defect if it's a problem with a particular part of the document.

In the discuss issue, we discussed the name of the label in this repo for issues which do not lead to any change. The description and name of the label were ambiguous. I have changed its name to agreement not to change, which @larsbarring preferred. Lars also wrote

I think that closing of issues that have gone dormant should not be done without "due consideration". I am not quite sure what that means in practice, but here is a strawman:

1. After M months (M=2 or 3?) of silence the issue receives the label dormant and the moderator, initial poster (and others??) receives a reminder email.
2. If nothing happens in D days (D=?, or one month?) the issue additionally receives the label committee attention.
3. [A subset of] the Conventions Committee periodically reviews (say every 6 month?) the committee attention issues and have a brief github (and offline if necessary) interaction resulting in
   • labelling the issue as inconclusive and then closing it (perhaps after a 7 day cooling off period),
   • assigning a moderator (as most dormant issues do not have a moderator) to resurrect the discussion,
   • taking actions to initiate an offline group (probably happens only rarely),
   • realising that this is a difficult question that could be the topic for a CF workshop discussion or breakout theme, label CF workshop. If the Workshop does not pick it up as a discussion/breakout theme, it should at least decide what to do with the issue, which might labelling it as inconclusive (then see 1.) or something else.
   • something else ??

As you probably have guessed this was inspired by the excellent standard name automation that @feggleton has set up

Thanks for this comment, Lars. I agree with the excellence of Fran's automation, and the desirability of greater clarity in this repo too. Before we consider the details of procedures and whether we could automate them, I suggest we decide on the categories we want. For simplicity, I would suggest that we introduce a dormant label which can be applied after some period of silence (to be discussed). It us possible that some dormant issues would then be wake up again, removing the dormant label, and proceed to change agreed or agreement not to change. Would that be sufficient (in terms of labels) i.e. one new one? Issue that remain dormant can be closed after some longer period (keeping the dormant label - perhaps never to reawaken, like a volcano, but useful for reference).

Best wishes

Jonathan

[larsbarring]

Yes, I agree that a dormant label would be useful (both here and in the discuss repo.) But what I was aiming at with my strawman is what happens to dormant issues -- in addition that they gradually moves out of focus, especially once they are not on the first page of listed issues, which is based on the newest sorting.

I do not think that a bot automatically adding the dormant label will elevate an issue to the first page again. Thus, identifying dormant issues will require the deliberate effort to either change sorting order to recently updated or specifically filtering the issue list on the dormant label. So, basically my questions are: how do we make this happen, and what do we do when we have this list of dormant issues?

[JonathanGregory]

Dear @larsbarring

I agree with you that dormant issues will not usually wake up by themselves, and that we need a process to deal with them. As chair of the conventions and standard name committee, I have an aspiration/responsibility/hope that we should put such a process in place, by consensus (as always), and use it to clear the backlog of dormant issues, over coming months. It would be nice to make substantial progress before the annual meeting, but we must be realistic.

How many months of silence indicates that an issue is truly dormant, and not just that people haven't yet had time to think about it and will still comment? You suggested two or three. I would have said longer, say six months, because I know that sometimes six months have passed before I had time to contribute a comment I intended to make. But perhaps that is too long to wait. What do others think?

Cheers

Jonathan

[JonathanGregory]

I posed these earlier as questions, which I'm now repeating as proposals:

I suggest we abolish the typo and style labels in the conventions repo. We can define defect to include typo, and enhancement to include matters of style of the conventions document.

Best wishes

Jonathan

[larsbarring]

Dear Jonathan,

Regarding you next to previous comment I agree with you. And I very much appreciate your ambition as chair of the committee! I am for example thinking of the very positive impact of your review of outstanding agreed standard names. My intention with suggesting a bot and some kind shared activity (responsibility is maybe a too strong word here) to look at dormant issues was/is to support you as chair and if possible distribute some of the work across more hands.

Regarding your thought that 2-3 months is too short I can easily agree. But if we settling for 6 months I think that the "reviews" should preferably be scheduled so that there is chance to come to a conclusion and make a suggestion in time for the release of next Conventions version.

Kind regards,
Lars

[taylor13]

I support abolishing the typo and style labels as proposed above.

I also think it a good idea to find ways of renewing interest in apparently dormant issues. The time-period triggering action might depend on the type of issue. For "defects", it appears that sometimes there is unanimous agreement (or at least no dispute) that a correction is needed, but then nothing happens for many months. I'm not sure why nothing happens, but it seems like for defects there shouldn't be such a long lag between agreement and implementation. [Or maybe I've just misinterpreted what has been happening.]

[JonathanGregory]

Thanks for your comment, Karl @taylor13. How many months of silence should define dormant, do you think?

I agree that defect issues are different from enhancements. For defect issues, agreement is by default, if no-one objects (that's already in the rules). Hence there is no reason not to implement them after three weeks of silence. I think the reason why nothing happens to some of them is that no-one takes responsibility for writing a pull request, and therefore we need a way to assign responsibility.

In some cases, it would be natural for the person who raised the issue to write the PR, but not everyone feels competent to do that. Therefore, I wonder whether at the CF meeting there could be a brief demonstration and introductory course for implementing a change to the conventions documents by preparing a pull request.

[taylor13]

I think more important than the number of months is what gets triggered to restart the clock. If a single objection suffices to renew life to a newly dormant issue and keep it active (until the clock runs out again), then I would not mind seeing issues declared dormant after 3 months. If, on the other hand, newly declared dormancy means that someone has to do lots of work (or committees meet) to keep it active, then 6-months would seem a better interval.

Regarding PR's, I must admit I'm scared I'll mess something up so haven't ventured there. I suspect there must be some very good tutorials online, so perhaps simply providing links to them might be a better (less burdensome) option than a introductory course at the CF meeting. The best tutorial would be one that provides the bare minimum one would need to create PR's on the github site. Or maybe someone could simply create a detailed recipe regarding executing PRs and post it on the CF website.

[JonathanGregory]

Since enough support was expressed and more than a month has passed, I have merged style into enhancement and typo into defect as agreed.

The question of when to apply dormant remains undecided, so I'm changing the name of this issue.

I also asked originally whether question could be abolished in this repo, and questions directed to the discuss repo. Any views?

[sadielbartholomew]

I'll chip in to help towards closing this. Regarding the final two labels:

Here's a question about questions: Should we have questions (about conventions) in this repo at all, or should such questions be asked in the discuss repo? If the latter, we should clarify this intention, and we won't need question or frequently asked question labels in this repo.

I think all questions should be kept in one location so that it is easy for people to search through open and closed questions in case they are wondering something along the same or similar lines and wanted to see if it has been asked before to avoid asking the same thing, etc. Therefore we should keep them in my opinion just under the Issue Tracker of the 'discuss' repo in this case (which seems most natural of the options between this repo and there). I'd suggest we transfer any issues opened here with questions, including ones currently open on the Issue Tracker with 'question' as the label. Issue transfer is very simple in GitHub, though we would need to assign one or more people the task of keeping an eye on things here now and again and making the transfer(s) when cases for them arise.

With that in mind, I wonder if maybe we can keep the 'question' label so that people can still easily raise a question using that, but transfer it as soon as we read over to 'discuss', and therefore I think a label such as 'moved to discuss [repo]' might be good to have. Either way we should make it clear questions should be raised in 'discuss', but there are usually cases where people don't realise and open something in strictly the wrong place, and keeping 'question' here won't put them off asking their question, albeit in the wrong place.

The question of when to apply dormant remains undecided, so I'm changing the name of this issue.

As for 'dormant', I think it is at least somewhat useful, and I certainly don't think there's any harm, in adding that label at the point when the bot under GitHub Actions adds the message to indicate things have gone stale for an Issue. It allows for those issues to be filtered in the search over Issues so they can be found more easily and hopefully in that way we can better manage getting the conversation re-started on those.

So I'd agree that 'dormant' is a label we should add and use.

[larsbarring]

Now, when I have been looking a little more actively in both this repo and the discuss repo, I must confess that I feel gradually more confused about the distinction between the two.

First I thought that the discuss repo was exact what is says; for discussions, new ideas and questions, and more. And this repo was for more specific, and perhaps technical or hands-on discussions regarding the Conventions text itself. But I find this distinction, of my own invention, diffuse and rather inadequate. Currently, the only clear distinction between the two repos that I can see is that pull requests of course are directed to this repo.

So, before having any particular view regarding a "questions" label I think it would be useful, for me at least, if we could clarify how the two repos are intended to be used. Then we can make it more clear already on the main page where to direct questions, feature requests, and other suggestions. And that would then make the basis for deciding on labels.

As an example, let us just assume that my initial distinction between the repos was right, then we might have something like:

• The following labels remainsagreement not to change, change agreed, conventions defect, duplicate, new contributor, standard name defect.
• The labels enhancement, frequently asked question and question are deleted in this repo but not in the discuss repo of course.
• The label GitHub usage probably goes to the discuss repo ?
• We also need a new label for "conventions changes agreed in the discuss repo", but this seems a bit awkward.

Another way to make the two repos more distinct is to direct all new issues to the discuss repo. And only if there is agreement that an issue has identified a defect it is moved from the discuss repo to here. This allows for a more clear separation between changes that have a short track towards implementation and those needing a longer cooling off or heads up time.

[JonathanGregory]

Dear Lars

Thanks for returning to this. I believe that the intention when we moved to GitHub was that this cf-conventions repo would deal with the conventions text, and discuss would deal with standard names and with any discussions that weren't proposals for specific changes. It was done like that because this is the distinction we had before GitHub between trac tickets and the email list, so it made the migration easy. But that isn't to say that it's the best organisation or that we have to stick with it.

I think this repo is where we make proposals and eventually pull requests to change the conventions, which are either defect or enhancement, so we need both of those. We also need change agreed, agreement not to change (though I'm aware we have not decided the criteria for that) and new_contributor. duplicate has hardly ever been used; it's one that GitHub provides. I'm not sure whether we need it. We might add dormant if we decide it's useful.

Conventions changes should never be agreed in the discuss repo. I would be content if questions about the conventions were asked in the discuss repo, and not in the his one, so I agree we could delete question in that case for this repo, and therefore also frequently asked question.

Would it be helpful to put the standard name issues in a different repo from discuss, which would then be only for discussion and questions (some of which might become frequently asked), and could include GitHub usage, for any of the repos.

The cf-convention.github.io repo is for the website. GitHub requires that it must have that name. Because the governance documents exist only on the website, that repo also deals with governance. This seems clear enough, I feel.

Best wishes

Jonathan

[ethanrd]

I hesitate to add another twist to this conversation but it seems inline with the recent discussion ...

GitHub Discussions can provide each repository a forum for discussions that is separate from issues and PRs. I believe it came out sometime not too long after CF switched from Trac to GitHub. The link above includes some text on when and how to use Discussion forums. Here's two sentences that summarize pretty well:

GitHub Discussions is best suited as a tool to share questions, ideas, conversations, requests for comment (RFC), resource planning, and announcements.

GitHub Discussions is best suited as a tool to share questions, ideas, conversations, requests for comment (RFC), resource planning, and announcements.

It wouldn't solve the labels issue. It looks like discussions, issues, and PRs on a single repository all use the same labels. However, the discussion forums have features that are specific to discussions, e.g., categories (Announcements, Q&A, Ideas) and marking helpful answers.

I expect the transition would take a good amount of work. So, if it seems useful, it should probably be split into a separate issue (in the Discuss repo?).

[ethanrd]

I've often wondered if standard names should be split into their own repository. I've mainly thought of it in terms of separating the standard names change tracking from the conventions document change tracking (and also separating the build and publish process). But separating the standard names discussions/issues would, I suspect, reduce some of the potential for confusion around where to ask questions or suggest changes.

[larsbarring]

Dear @JonathanGregory

I will respond to your comment in reverse order:

• Yes, I totally agree that the function of the cf-convention.github.io repo is clear enough.
• Regarding splitting the discuss into one dealing with standard names and one for all other questions and discussions I have, as you and @ethanrd do (and @sadielbartholomew gives a thumb-up), asked myself the same question several times. But I tend to remember that there was some discussion about this several years back and the outcome was to not make a split (maybe @japamment have some insight?). On the other hand, given how things have evolved I think it would be motivated to think about this again.
• To move discussions over to the github discussions functionality that Ethan points at, I have no insight or experience at all. But given that it would require a fair amount of work, I wonder whether we still can improve the situation with smaller changes how the two repos (discuss and conventions) are presented at the main github page and at relevant places in the Convention website. This, together with the being more selective in what labels we use much like you suggest, I imagine would help out a fair bit.

[ethanrd]

Hi Lars @larsbarring - I agree moving to GH Discussions would be a good amount of work and take time. I definitely think the changes you and Jonathan have been discussing will improve the situation and not take nearly as long as a switch to GH Discussion.

[larsbarring]

Hi Ethan @ethanrd, Thanks for the support.
@JonathanGregory, I think that we now are discussing two things:

1. How to make the distinction between ths repo (cf-conventions) and the discuss` repo more distinct, so that the former focusses more on the Conventions text as such (how to implement enhancements in the text, iron out defects or typos, etc.), and the latter on a more general discussion about enhancements and new features or standard names, as well as questions and clarifications.
2. Whether it would is is useful to fork off discussion on standard names into a standard namesrepo separate from the currentdiscuss repo.

If this is a reasonable description of where we are, then we could perhaps focus the discussion in this issue on the first point?

My thinking is basically as follows:
If I look at the main CF github page there is a brief explanatory text for each repo (e.g. "AsciiDoc Source" for the cf-conventions). For the discuss repo I think the text is just fine. But for this repo the text could be expanded to something like:

AsciiDoc Source for the CF Conventions document. Issues in this repos should deal with implementation 
of enhancements in the text, iron out defects or typos, etc. Questions and more general requests for, 
and discussion about enhancements and new features is directed to the [discuss](_link_) repo.

This text, in combination with corresponding changes to issue templates, and the questions template is removed altogether.

And then the labels are changed as we discussed (and agreed I believe), i.e.

• agreement not to change, change agreed, defect, enhancement remain
• frequently asked question, question are deleted
• duplicate, new contributor are deleted
• GitHub usage in all three repos?

For the discuss repo the following changes to labels would be needed:

• defect is removed, ore relabelled to standard name defectas general text defects should be dealt with in the cf-conventions repo
• duplicate may be removed (but might be more motivated to keep it here)

Finally, the explanatory text in the issue template is updated.

---

I think these changes would help to clarify for the user the intended distinction between the two repos.

[DocOtak]

All, I would support a move to github discussions eventually (specifically in this repo here). My memory matches with @ethanrd that GH Discussions arrived within a few weeks of CF adopting a discuss repository. I think it was wise not to adopt a very newly public github feature immediately.

I think it would help with the specific workflow that we have going: discussion -> formal issue -> pull request. When everything is in the same repository/project on GH, I've found that all the referencing becomes trivially easy. Discussions can be directly turned into issues and vice versa. Additionally, defaults are important and by default, github does not search closed issues. While you can close a discussion it opens more options such as "answered" as an end state to the general discussions and questions that show up. I also think that the phrasing of "discussion" is more welcoming than "issue" when someone has a usage question.

[larsbarring]

From my side I have nothing against moving to github discussions, but I am not experienced enough a github user to be of any assistance.

[JonathanGregory]

Dear @larsbarring, Andrew @DocOtak, @ethanrd

I agree with everything Lars has said, except that:

• new contributor should be kept for this (cf-conventions) repo. That label is for marking issues where someone has substantially contributed to the discussion who isn't already in the list of contributors.

• in the discuss repo, I don't think we need to rename defect. In that repo, it refers to standard names. The explanatory text for labels should say so, and also the template for raising an issue should say that this is not for defects in the conventions text.

I understand the purpose of duplicate but it doesn't seem useful for our way of working, except that I can see that it might be useful to label something as duplicate as a reason to close the issue, as an alternative to agreement not to change and change agreed (and perhaps dormant, to be discussed later) in this repo. In the discuss repo, duplicate could again be a reason to close an issue.

I suppose GitHub usage could be used in any repo, according to which is relevant, but what if the issue applies to all repos? Does that mean we should designate one of the repos as the place for discussions about GitHub?

Once we've agreed these changes to labels, we can consider your (2) about splitting standard names and discussions, and the question of GitHub forums. What Andrew says about the latter suggests that we could have a forum in each of the repos, for the matters it deals with. It's useful to know that discussion threads in the forum can migrate into issues for action in the repo. If we reorganise things like that, it probably addresses (2) as well. The discuss repo would change to being for standard names. Discussion about standard names would take place in its forum, and discussion about conventions in this repo's forum, if I have understood correctly.

Cheers

Jonathan

[larsbarring]

Dear @JonathanGregory,

I am happy to accept all your points about labels. Regarding (2) and GH discussions, I think this looks like a way forward.

Thanks,
Lars

[JonathanGregory]

Dear all

Thanks for the discussion yesterday about Discussions. The proposal I reported yesterday, from the CF committee, was to repurpose the discuss repo for vocabulary specifically, with questions about conventions to be asked in the conventions repo. That would be better than the current situation, where it's not clear which repo should be used for questions about conventions, and the result is a mixture.

Following Andrew @DocOtak's advocacy of GitHub Discussions (capital "D" to indicate the technical facility of that name!), @ChrisBarker-NOAA remarked in the zoom chat that one can have Discussions for a whole organisation. The GitHub doc about this says "You can use GitHub Discussions in an organization as a place for your organization to have conversations that aren't specific to a single repository within your organization. ... When you enable organization discussions, you will choose a repository in the organization to be the source repository for your organization discussions. You can use an existing repository or create a repository specifically to hold your organization discussions. Discussions will appear both on the discussions page for the organization and on the discussion page for the source repository."

I think organisation Discussions is appealing as a way to reconcile the two different motivations we talked about yesterday in the meeting. (1) As several people remarked, it would be good to have a single forum in which questions can be asked and discussions held, without having to decide whether it belonged to conventions, vocabulary (standard names etc.) or website/governance. (2) We can manage changes more easily and clearly, through issues for enhancement and correction of defects, if we have different repositories for these three areas, which each have their own set of documents.

That leads to this alternative proposal:

• We use a repo named discuss to host GitHub Discussions about the cf-conventions organisation or any of its repos.

• In the discuss repo, we use categories such as "announcement", "question" or "discussion". I think it would be good not to have too many categories, and to distinguish clearly among them (as you can for those three purposes), because that will help us to manage them. I have no experience, but it looks like you choose a category when beginning a discussion.

• For discussions, we might use labels, added manually and later, if they're useful to indicate things which happen as a result of the discussions. Those could include frequently asked question (to label it as something to be added to the FAQ) and answered (for questions, as a reason for ending the discussion). Maybe there are other labels to indicate reasons for concluding discussions. We might also use labels to indicate, if it was useful, whether a discussion related to conventions, vocabulary, or website/governance, if it was clearly one of those.

• We should have three other repos. Two of them would be the same as now: cf-conventions for the conventions, and cf-convention.github.io for website and governance. The third one would be e.g. vocabulary, for the standard names and other controlled vocabulary. That is, we would split the current discuss into discuss and vocabulary. Within each of these three repos, there would be enhancement and defect issues for proposing changes, just as now, except that we would use enhancement for a new vocabulary proposal (currently labelled standard name in the discuss repo), like we already do in the other two repos. We would not have questions or announcements in any of these three repos.

What do you think?

Best wishes

Jonathan

[larsbarring]

This looks like a good way forward to me. Thanks.

A couple of question of clarifications:

• Should we have any issues (at all) in the new discuss repo, or should it only be a placeholder for discussions?
• What happens when a discuss discussion converges towards a suggestion for enhancement?
  • is the whole discussion transferred to an issue in either the cf-convention or vocabularies repos?
  • or is is used as background for starting a more targeted issue in the appropriate repo?
• What should we do with issues already existing in the current discussrepo?
  • should they be actively moved to either the cf-convention or the new vocabularies repos?
  • or should they gradually be taken care of and eventually closed for one reason or another?

Yesterday I remarked in the chat that we have seen problems (at least one) with issues "disappearing" when moved from one repo to another. I will open a separate issue on that and ping the Info management team. (my mistake)

[DocOtak]

We didn't talk about this at the hackathon today (enums were more popular than project management), I had done some digging around for examples of usage. The github blogpost introducing organizational level discussions gives the Homebrew project as their example:

• The organization landing page: https://github.com/Homebrew has a Discussions tab at the top
• Here is their Discussions page: https://github.com/orgs/Homebrew/discussions
• This is the "host repository" for those discussions: https://github.com/Homebrew/discussions

Github has some guidance on how to use these features: https://docs.github.com/en/discussions/guides/best-practices-for-community-conversations-on-github

I think we can even select the existing discuss repository as the "host repository" for the organization wide and convert all the existing issues into Discussions: https://docs.github.com/en/discussions/managing-discussions-for-your-community/managing-discussions#converting-issues-based-on-labels

I mostly agree with what @JonathanGregory proposed except to the splitting the current discuss issues up. The organization level Discussions should be the single entry point to where someone should start their questions or proposals for changes to the conventions or standard names (real life discussions at meetings is ok too but should result in a record online). Since the vocabulary is largely managed via external tools, having a separate repo for it is mostly a technical implementation detail.

Some potential workflows:

• Standard Name Proposal
  1. A discussion is started in Discussions in a Standard Name category (this provides some significant isolation from other questions)
  2. debate occurs
  3. final names and definitions are agreed to
  4. either marked as accepted/answered and/or issue is opened with the final proposed text in the vocabulary repository, I think the opening of an issue is optional because vocab is managed external to github and I would defer to the vocab management team to how they want to
  5. published name table xmls etc.. occur in the vocabulary repository
  6. Close any open issues/pull requests related to this, mark the question as answered
• Conventions Change
  1. A discussion is started somewhere in Discussions (open to category suggestions)
  2. debate occurs
  3. we agree to accept the proposed change
  4. an issue is created in the conventions repo (from Discussions) to work out the specific text details. going back to the Discussion if large issues arise
  5. a pull request with text changes is created noting that it will resolve the open issue in the conventions repo
  6. pull request merged, issue is closed, Discussion marked as resolved somehow (answered?)
• Someone New Has a Question
  • A discussion is started in Discussions in a Help/Questions/Getting Started category
  • We discuss
  • we hopefully answer the question, no other repositories are involved

Basically, Github issues are meant to be very focused and specific to the repository they are attached to and anytime someone asks themselves where to ask a question propose anything, the answer should be the CF Conventions Organizational level Discussions. Even most if not all the Issues in this issue tracker (rather than the discuss one) should probably be moved to Discussions.

I'd actually like to try some of these features (perhaps in a test/mirror organization) before we commit CF anything. I'm also keen on sorting out these details in a more real time communication medium if we don't have time at the workshop

---

I tried to follow the capital D Discussions when I mean the github feature in the above

[ChrisBarker-NOAA]

Thanks @DocOtak: I agree on all counts. Personally, I'd probably just set it up in the CF org, but yes, it's a good idea to test it out some first :-)

[JonathanGregory]

Dear Andrew @DocOtak

I think it's better to have a separate discuss repo from vocabularies (i.e. splitting them up) so that the latter contains only issues for modification of vocabulary changes (mostly standard names). It's not really logical to have discussion issues on all subjects in the same repo as the standard name and vocabulary issues and documents. There's no good reason why it should be that repo rather than either of the others. The actual reason why discussion and standard names are currently in the same repo is just historical; it's because they were both formerly dealt with on the same email list, while conventions were in the trac system. It made the migration to GitHub easier, but now we're settled in GitHub it would be good to sort them out.

Thanks for describing workflows. I don't think it's necessary for standard names and conventions proposals always to start in the Discussions. Sometimes, when it's not clear what to do, that would be helpful, but for many proposals it would be an unnecessary stage. I feel that it's better to continue with the present arrangement, where a proposal can be debated extensively and modified in a conventions or standard names issue before it becomes firm enough to turn into a pull request. If we did this partly in Discussions, and partly in an issue, it would be harder to follow the discussion at the time or subsequently. In practice, there is not a clear distinction between discussion of the change and discussion of the wording.

I think the current arrangement with issues for enhancements or defections of defects in vocabulary, conventions and the website/governance is generally fine. The difficulties we need to solve are the confusion about where to ask questions, and where to have discussions when you don't have a firm proposal in mind. If a Discussion concludes that a change is needed, at that point it should continue as an issue in the relevant repo. Lars asks whether the previous Discussion should be converted into an issue. That would have the advantage of keeping it in one place as a record. On the other hand, a single Discussion might lead to several issues, possible in different repos (both conventions and standard names). That's an argument for not migrating the DIscussion.

If the Discussion is an additional feature, as I'm advocating, we could introduce it to the CF organisation as the new place for questions, discussions and announcements. We don't have to modify the workflow in other ways.

Best wishes

Jonathan

[DocOtak]

@JonathanGregory I am strongly opposed to more discrete locations to start discussions/issues. This very issue (#440) is an example for me. I knew we were taking about this, received a notification as such on the GitHub app on my phone, but since I want to respond by typing on my computer keyboard (rather than my thumbs on a touch screen) I went looking for where to reply in https://github.com/cf-convention/discuss/issues and was rather confused for a bit. So my feeling is: if I'm confused about an active discussion that I'm participating in and I've been involved with CF for a while, new contributors are likely to be impossibly lost.

I think your desire to have separation is largely covered by the Discussion categories. These Categories are not optional and when you go to create a new discussion, github forces you to pick a Category for that discussion to occur in. To me, this has the advantage of guiding me to right place to have a discussion rather than needing to look for the right place, which has some requirement that I even know there is a right place. You can even restrict who can post in certain categories (e.g. only CF Committee members can post in the Announcements category).

As for converting specific Discussions into Issues, the github workflow appears to be Create from Discussion with the key being the following:

Creating an issue from a discussion does not convert the discussion to an issue or delete the existing discussion.

I suspect that creating multiple issues from a single discussion wouldn't be prohibited by the tools.

I know of at least one project where all issues (including bug reports) must originate in a Discussion: https://github.com/pradyunsg/furo (click on both the Issues and Discussions tabs to see how they do this)

I was really hoping to try out all these tools together in one of the hackathons, would you (@JonathanGregory) and other stakeholders (guesses: @ethanrd @japamment @erget @davidhassell ) be open to arranging a time to try this together? I could also try some things on my own and invite participation/demos afterwards.

[JonathanGregory]

Dear Andrew @DocOtak

If we had already had Discussions, that's where we might have begun this discussion, especially because labels are an issue that applies to all repos, not just this one. I agree with you that plenty of existing issues could have started as Discussions, because it wasn't clear what would be proposed, and perhaps given rise to issues. But in some other cases, it is clear what you want to propose, so why not do that, in the appropriate repo, if you know which one is it. In most cases, it would be clear whether the proposal relates to conventions, standard names or the website, each of which has its own repo.

If we create a Discussion facility, we can do it now in the present organisation, and start using it to see if it's better, with real subjects. This doesn't require us to change our workflow completely, as you suggest. It's an evolutionary approach. It may turn out that most issues start as Discussions in practice, as you suggest. Why not try it and see? I'm definitely willing to try it out myself, and thanks for advocating it.

It's good that the category is mandatory for a new Discussion. I suggest they should be discussion, question and announcement, which are easily distinguishable. You could have separate categories for discussions about conventions, or about standard names, but that would require the user to know which it was. Being able to avoid that is one of the advantages of using a Discussion instead of an issue in the repo.

Best wishes

Jonathan

[ChrisBarker-NOAA]

gitHub has always been a challenge (and TRC before it!) when working with multiple related repos -- where does a given "thing" go when it might affect more than one repo? or the user isn't sure which one it belongs in?

I think having a clearly marked org-level Discussions will really help here -- then the actual repo issues can be trainged an put in the right place when the time comes.

[JonathanGregory]

I agree with @ChrisBarker-NOAA that having an org-level Discussion will be very useful. It could be the best place to start many things that become definite proposals (on issues) later.

[erget]

Happy to support piloting of this.

[JonathanGregory]

I have changed the title of the issue, as recorded above, because we now have a CF organization Discussions forum. Therefore labels are the remaining topic of this issue.

Discuss issue #346 proposes that in future all questions will be asked as Q&A Discussions, not as issues. Presuming agreement on this, which looks likely, we will no longer need the question or frequently asked question labels in this (conventions) repo, if we move all the questions from this repo to the Discussions. I propose that we should do that, and label them as conventions there so they can be found easily.

Lars and I agreed the following about labels in this repo, and I don't think anyone disagreed:

• frequently asked question and question are abolished. Sadie suggested we might keep the question label in case someone opens one here although they shouldn't. I feel we should follow the practice of the vocabulary team, who plan to convert into Q&A Discussions any questions that are asked as issues in the vocabularies repo.

• defect, enhancement and GitHub usage remain. These should given to issues automatically when they are opened, to identify the kind of change proposed. GitHub usage is about its use in this repo specifically.

• agreement not to change and change agreed remain. They are labels to be applied as reasons for closing an issue.

• new contributor remains. This label is added manually by moderators to indicate that a significant contribution was made to the issue by someone who should be added to the list of contributors.

Separately in this issue, and in the CF committee, we discussed the dormant label. This is a reason for closing an issue. Since the committee discussed it, I have begun to use it in the following manner. If an issue has been silent for more than six months, and has not concluded, then I write on the issue to encourage any interested person to resume it within three weeks, if they wish it to remain open, flagging some with their GitHub handles. I also email them if I can. If it is not resumed with three weeks, then I close it with the dormant label attached. Although it's just me who's done this so far (as chair of the committee), I suggest that this procedure could be followed by anyone, just as anyone can be a moderator. Dormant issues could be reopened, and there's a link to dormant issues on the discussion page.

We currently have a duplicate label. Lars and I agreed thought that this could be abolished. On second thoughts, I think it is worth retaining as another reason for closing an issue i.e. it's the same content as another issue (although this is unlikely).

I propose we add a governance label to this repository, if we agree #369, to merge CONTRIBUTING and rules into one file in this repo. Since the rules for changing the conventions will then be hosted in the conventions repo, we will make proposals to change them by opening issues in this repo. Hence governance, which we also use in the governance/website repo, would be a label for new issues. The meanings and use of the labels in this repo should be described in that file.

Does anyone have comments on the above?

Best wishes

Jonathan

[larsbarring]

Many thanks Jonathan! -- This looks all good to me. /Lars

[davidhassell]

Thanks, Jonathan. The labels and their usage describe in #440 (comment) all look good to me.

[sadielbartholomew]

That also sounds good to me, thanks for creating and outlining a plan Jonathan.

[JonathanGregory]

I'm glad that you're all in favour. Since there's enough support been expressed, these changes will be accepted in three weeks, on 22nd September (just after the CF meeting finishes), if no-one expresses concerns by then.

[JonathanGregory]

I have made the changes to labels in this repository as agreed in this issue.