Update topic tags for better discoverability

[aidanheerdegen]

We need better discoverability of repos in the organisation.

To do this we need to be able to link to categories of topics in the top level organisation repo.

For this we need a controlled vocabulary of topics, and every repo should have a topic tag from this vocabulary.

[ccarouge]

To do:

• get spreadsheet of all ACCESS-NRI repos, including topics used for that repo if possible (Tom)
• decide on controlled vocabulary of topics for the "mandatory" categories
• add one or more "category topic" to each repository
• add links to searches on "category topics" to the org README
• decide on controlled vocabulary of topics for wider use
• add info about topics to the org README ? Or just update on dev-docs?

[ccarouge]

@micaeljtoliveira , at our meeting, you listed categories of software you had identified in the ACCESS-NRI org. Would you mind adding them here to use as a first pass at defining categories/topics?

[micaeljtoliveira]

@ccarouge Here you go:

• Model components
• Forks of model components
• Configurations
• Model evaluation tools and scripts
• Model configuration tools (e.g. om3-scripts)
• Internal tools (e.g. things related to telemetry)
• Dependencies of model components (usually forks)
• Spack infrastructure
• Spack environments
• Documentation
• Web content

I'm probably missing some things and it's obviously only one specific way of classifying the repos, but it's probably a good starting point for further discussions.

[CodeGat]

In the GitHub Management Group meeting today (with @aidanheerdegen, @micaeljtoliveira, @ccarouge) we noted the following topic groups should be added to relevant repositories:

• Model-related Topics: These topics note that a given repository is associated with a climate model, either through being code for a given model, a model deployment repository, or a component of a larger model/s.
  • ACCESS-NRI/ACCESS-OM2 would have the topic access-om2 as it is a model deployment repository
  • ACCESS-NRI/MOM5 would have access-esm1p5, access-esm1p6, access-om2 as it is a component of those models
• Type-related Topics: These topics note that a given repository is a certain type. They are mutually exclusive. For example:
  • tool: For general software.
    • ACCESS-NRI/system-tools
  • deployment: For repositories whose contents are deployed by ACCESS-NRI.
    • ACCESS-NRI/ACCESS-OM2 as it is a model deployed via spack to Gadi.
    • ACCESS-NRI/payu as it is software deployed via conda to Gadi.
  • documentation: For repositories whose purpose is primarily documentation
    • ACCESS-NRI/dev-docs and ACCESS-NRI/access-hive.org.au
  • configuration: For repositories that house Model Configurations
    • *-configs repositories like access-om2-configs, access-om3-configs...
  • component: For repositories that are components of climate models
    • For example, ACCESS-NRI/MOM5
• Deployment Method Topics: For repositories that have the deployment topic, through what means are they deployed
  • spack, conda, etc...
• Earth System Topics (not sure if this is the actual proper name): This notes that a given repository is relevant to a particular earth system
  • For example, regional, biogeochemistry, chemistry

[CodeGat]

As for examples with these topics (minus the *-team topic which might be deprecated) :
A Model: https://github.com/ACCESS-NRI/ACCESS-OM2
A Model Component: https://github.com/ACCESS-NRI/MOM5
A Tool: https://github.com/ACCESS-NRI/system-tools
A Documentation Repo: https://github.com/ACCESS-NRI/dev-docs

[micaeljtoliveira]

@CodeGat Thanks for the summary and for the examples. There are a couple of topics we mentioned that are missing though: fork and template (I took the liberty of adding fork to the MOM5 repo).

I also did some searches to test the usability of the topics to find things in the org. It's a bit cumbersome having to explicitly write topic:FOO for all topics one wants to match, but otherwise works as intended.

There is however one catch that I was not aware of: by default, forks are excluded from the search. One needs to add fork:True to include them. For example, this search will find the MOM5 repo, but not this one. Not a big issue, but worth mentioning (although I suspect most of you already knew this).

[CodeGat]

Thanks for adding those @micaeljtoliveira !

Good pick up regarding the forks - in gh search repos the equivalent flag is --include-forks=true

[ccarouge]

Thanks @CodeGat . A small remark, should tool and deployment be mutually exclusive? You say the type-related topics are mutually exclusive topics, which is true for all except maybe these 2. I wonder if it actually matters to decide whether only one should be used or not. We could leave it to people to use their brains. If people find their repositories need 2 typ-related topics, then they should go for it.

Another category missing is licence. We discussed having this as a topic.

[CodeGat]

You're right, those two shouldn't be mutually exclusive.

As for the license field, I thought that was a special field searchable outside of topics. At least, in gh one can search for them without topics with gh search repos --owner access-nri --license LICENSE, so I assume there is a way in the web UI

[micaeljtoliveira]

As for the license field, I thought that was a special field searchable outside of topics. At least, in gh one can search for them without topics with gh search repos --owner access-nri --license LICENSE, so I assume there is a way in the web UI

Yes, it's possible, so I would say we don't need this as a topic (using the license option on the web UI is actually more convenient, as it provides a drop-down list to select the license from).

[micaeljtoliveira]

I've gone through the above proposal and had a go at modifying the current dev-docs wiki section on GitHub topics. This is what I got. Let me know what you think.

Topic tags

Introduction

Our GitHub organisation has well over 100 repositories and it can be difficult to browse or find repositories:

https://github.com/orgs/ACCESS-NRI/repositories?type=all

As an organisation we are using topic tags on repositories to help with discovery. There are a few broad categories of topics:

• Model: These topics note that a given repository is associated with a climate model, either through being a model component, a deployment repository, model configurations, etc. Some examples:
  • ACCESS-NRI/ACCESS-OM2 has the access-om2 topic, as it is the model's deployment repository.
  • ACCESS-NRI/MOM5 has the access-esm1p5, access-esm1p6, and access-om2 topics as it is a component of those models.
• Type: These topics note that a given repository is of a certain type, like a model component, documentation, a model configuration, etc. Some examples:
  • ACCESS-NRI/ACCESS-OM2 has the deployment topic, as it is a model deployment repository.
  • ACCESS-NRI/MOM5 has the component topic.
• Deployment method: For repositories that have the deployment topic, through what means are they deployed (spack, conda, etc).
• Earth systems: This notes that a given repository is relevant to a particular earth system. For example:
  • ACCESS-NRI/ACCESS-OM2 has the ocean, sea-ice, and biogeochemistry topics.
• Other: These are topics that indicate some properties not covered by the previous categories. For example, repositories that are forks should have the fork topic.

Next is the full of list topics currently in use, per category (in alphabetical order):

• Model
  access-am3
access-esm1p5
access-esm1p6
access-esm3
access-om2
access-om3
access-ram3
• Type
  configuration
component
deployment
documentation
tool
model-evaluation
• Deployment method:
  conda
spack
• Earth system:
  atmosphere
biogeochemistry
carbon-cycle
coupler
ice-sheet
land
ocean
sea-ice
waves
• Other
  fork
template

Bellow are some examples of searches using these topics.

All repositories related to ocean models:

https://github.com/search?q=topic%3Aocean+org%3AACCESS-NRI&type=Repositories

or sea-ice

https://github.com/search?q=topic%3Asea-ice+org%3AACCESS-NRI&type=Repositories

All spack deployment repositories:

https://github.com/search?q=topic%3Adeployment+topic%3Aspack+org%3AACCESS-NRI&type=repositories

Note that search function on GitHub, by default, does not include forks. To include forks in the search one needs to add the fork:true option.

[micaeljtoliveira]

There are also a few topics mentioned in the current documentation or used in some repos that I'm not sure if we want to keep or in which category to put them:
actions
apache2
build-ci-enabled
cable
cmip7
coastri
coupling
cylc
deprecated
documentation-website
grafana
infractructure
inputs
jules
library
model
no-backup
payu
python
reporting
reproducibility
roms
testing
unified-model
visualisation
working-group

Another thing is that we are currently using model-configuration in the org, but in the proposal above we used componentconfiguration. Which one shall we use?

Finally, should we add a training topic to the "Type" category? There seems to be a few repos for which this would be a better fit than documentation I think.

[CodeGat]

I think model-configuration are for model configuration repos, right? The *-configs ones?

Furthermore, if you could keep build-ci-enabled that would be great - I use it to quickly search for all repos that use the build-ci entrypoint workflows.

[micaeljtoliveira]

I think model-configuration are for model configuration repos, right? The *-configs ones?

Yes. Sorry, I made a mistake in my previous comment. Fixed now.

[ccarouge]

I would only use configuration for the reason that topics are meant to be stacked on each other to create a more precise search. For the same reason, I would use evaluation and not model-evaluation. At least, I wouldn't have evaluation and model-evaluation unless it's absolutely necessary to highlight the difference with topics (@rbeucher comment?)

Do we want to add a model topic to all model repositories to specify their type? Is that useful?

In the list of topics you gave @micaeljtoliveira:

• jules, cable, unified-model, roms are model component names. Here, it depends on what we want to do. For example, this deployment repository is to deploy CABLE. So only cable would fit as a model name. If we want a model topic, then we need cable, if we don't want to enforce a model topic on all model repositories, then we may not need it. I suspect it's the same for the other ones (or some of them). At the same time, unified-model on the UM repository (with name UM) is redundant... I think the idea initially was to identify all repositories that need the UM (ACCESS-ESM1.6 would have the unified-model topic). I'm surprised there aren't mom and cice ones.
• payu, cylc: it was to identify which configs used payu or cylc (I believe). I don't know if that's useful.
• infrastructure: it depends on whether we need this as a type??
• documentation-website: I would replace with documentation
• visualisation: I would keep as a type
• testing, apache2, python: remove, deprecated: remove repos should be archived/deleted if they are deprecated
• no-backup: @CodeGat is that required for the backup system?
• inputs: could be useful to identify tools that are used to create model input files?? Like a Earth system category for tools
• coastri, cmip7: I think I'd prefer steering away from topics about funded projects, but I don't have a well articulated reason.

I let other people weigh in for the other ones.