Repository organisation and descriptions

[dylanjmcconnell]

As part of recent discussions about an update / refresh of the CEEM website, the list of open-source tools came up. There are currently 12 tools listed on the website - an incomplete list, with some of the tools not particularly being particularly active or up-to-date.

This prompted the need for bit of "review" of the repo - with a view to:

• update the CEEM website
• re-organise and describe the repo's better here

Basically to better reflect the status of the repo's, and better communicate / manage expectations for users of the tools / libraries (e.g. for example, if a project is active, likely to respond to PR's / issues etc). Perhaps some of them should be archived (i.e. converted to an archived git repo - read only, but still available) or perhaps status needs to be clear / described upfront.

This discussion has been created to work out what best to do:

• the first section just gives a bit of an overview of what is in the org at the moment
• the second section raises issues some potential options (for discussion)
• the final section flags some other miscellaneous things

UNSW-CEEM org summary:

• 52 repos (33 public · 19 private) · 328 ⭐ · 127 forks
• 1 archived · 6 forks
• Languages: Python (31), Jupyter (6), HTML (4), others (11)

"Activity"

(estimated / based on last push)

Bucket	Public	Private	Total
Active (<6 mo)	8	4	12
Recent (6–12 mo)	3	1	4
Stale (1–2 yr)	4	1	5
Dormant (2–4 yr)	9	11	20
Abandoned (4 yr+)	9	2	11
Total	33	19	52

Around ~70% of repos haven't been touched in 2+ years. (with some of the private repo's being particularly dormant)

"Top" repo's

Crude assessment / ranking of repo's by stars, forks, contributors, and commits (for the "top" repo's) - no shade intended

Repo	⭐	Forks	Contribs	~Commits	Status (based on commits)
NEMOSIS	95	37	7	281	active
nempy	68	37	8	455	active
energy-market-deep-learning	56	20	1	108	dormant (2022)
NEMSEER	34	7	3	590	active
NEMED	15	6	3	73	stale (2024)
nem-bidding-dashboard	10	5	5	108	stale (2023)
DER_disturbance_analysis	6	1	12	453	stale (2024)
TDA_Python	6	1	6	362	dormant (2023)

Potential issues and options

The issues (as I seem them) is basically that many of these projects are not active or maintained, but this is not really communicated anywhere.

It perhaps would be useful to elevate / highlight the repo's that are active and "supported" for discoverability and people that come across the org and list of tools. Similarly, it would perhaps be useful to communicate that some projects are here for reproducibility / research records, or archieval purposes - but maybe they aren't up-to-date, working, or supported in anyway.

Standard status

The standard repostatus could be drawn upon - these include:

Concept – Minimal or no implementation has been done yet, or the repository is only intended to be a limited example, demo, or proof-of-concept.
WIP – Initial development is in progress, but there has not yet been a stable, usable release suitable for the public.
Suspended – Initial development has started, but there has not yet been a stable, usable release; work has been stopped for the time being but the author(s) intend on resuming work.
Abandoned – Initial development has started, but there has not yet been a stable, usable release; the project has been abandoned and the author(s) do not intend on continuing development.
Active – The project has reached a stable, usable state and is being actively developed.
Inactive – The project has reached a stable, usable state but is no longer being actively developed; support/maintenance will be provided as time allows.
Unsupported – The project has reached a stable, usable state but the author(s) have ceased all work on it. A new maintainer may be desired.
Moved - The project has been moved to a new location, and the version at that location should be considered authoritative. This status should be accompanied by a new URL.

However, these are more suited to standard open-source software practice (.. and where a maintainer might actually exist and/or be supported). A lot of our code and tools might not fit with this - and are tied to particular projects or grants, or papers - and the reason for keeping them visible and available is for reproducibility and other more specific / research related reasons. Some of the above language might be a bit "harsh" in this context - (e.g. abandoned - which might true in a software sense) - so maybe a different taxonomy could be used.

Alternative / research oriented status

So perhaps a more CEEM / research oriented status could be used. A potential / speculative taxonomy could be along lines of:

Status	Meaning
Active research	Currently developed under a live project or grant - but maybe more polished (c.f. "exploratory" - see below
Released - (limited support)	Used by others; bug fixes & questions answered, no new features
Project output (preserved)	Tied to a completed project/grant; preserved as-is for reuse and reproducibility, not intended to evolve
Dormant	Project paused, not actively developed (between grants, students, collaborators), but still want to maintain visibility / hold out some hope of it being revived somehow
Exploratory / WIP	Prototype / work in progress (unstable, not for general use) - perhaps overlaps with active research?
Superseded	Replaced by a successor (possibly in git archive)
Archived	Frozen, read-only (moved to git archive - I think different category to preserved project output, and think a couple of repo's might fit this category)

These are just suggestions to be potentially refined / worked on - idea would to probably highlight / elevate the active and released repo's (on the CEEM website and in the github repo - both the org readme, and maybe individual repo's as well).

You would have table describing these categories on the org page, and then a badge (and/or short message) at the top of each repo to clearly communicate this. e.g. like

Potentially in combination with:

Warning

This project is currently not actively supported

Or:

Note

This project is currently support by X grant

Both

A third option would be to classify projects on both the standard taxonomy, as well as a more bespoke / research oriented taxonomy (Though I think this is probably a bit messy and doesn't really get around the issue of the different objectives / use cases - i.e. software vs research objective)

Steps forward

I think worth checking in with folk before trying to actually trying to "classify" the existing repo's - see what everyone thinks etc. The above are just suggestions that might need to be refined.

We might also thinking about adding in a person as the contact point or responsible person for particular repo's (this might be another discussion - re: divy-ing up maintenance burden). And maybe you would only do this for a subset of the categories we land on.

Miscellaneous

1. Some CEEM related repo's are actually in other personal github repo's (nemo and the ppa_analysis tool come to mind). Not necessarily a bad thing - but not captured in the org repo at the moment (would think it would make sense to at least mention or link to them in org readme?). There maybe others too - they are just the ones I know of.
2. There's a couple of repo's that have papers associated with them, but no CITATION.cff - probably worth adding that (for discoverability / consistency)

[EllieKallmier]

I am pro 'bespoke' research/CEEM oriented categories! I don't personally think the standard software labels are that useful for our case (for the reasons you've described already) - and agree that prob mixing the two just adds clutter more than usefulness.

Tbh I like most of the suggested categories here too, though I think that we can workshop them a little to clarify a few things. The repos that feel like they might be harder to categorise (to me) are for example released, 'project-finished' but still actively maintained and updated repos (e.g. nempy and NEMOSIS - though ofc @nick-gorman is much better placed to comment on this). This and the potential overlap between the WIP / Active research could be finessed I reckon - maybe there are some things that we leave to be described by e.g. package release versions (if package), like stability.

To that point, I'm also a fan of the Warning/Note kind of extra context messaging (but as an extra feature where needed, not a necessary feature).

Re: the steps forward note on assigning contact people - yeah I reckon this is part of a bigger team discussion about our high-level aims for/approach to long term management of tools/scripts/repos. I lean towards not adding this for the moment while we're still at the categorising step, because at least for the "active" repos we can keep just encouraging people to open Issues or PRs as the way to contact maintainers (so it's not like there's no way atm to get in touch). But once we've got a bit of a plan overall it could be the move!

Will keep having a think on the categories too!

[dylanjmcconnell]

Yeah cool and totally agree re: nempy and nemosis being hard to categorise - this is kind of what I had in mind re: "Released - (limited support)" - but maybe needs some work / clarification. Not currently funded, but still partly voluntarily maintained .. and yeah Nicks input very important here.

(..and agree the maintenance question best for another day).

[arastoote]

Thank you Dylan for this. The idea of tagging/classifying repos is great. I also think the current high-level grouping in the CEEM GitHub org (such as NEM and DER/CER) is already a good starting point, but perhaps these categories could be rearranged into something more practical from a user perspective, if there’s a clearer structure.

For example, dormant or legacy repos could potentially be hidden from the first/main page or separated from the main active categories like NEM and DER, while still remaining accessible for reproducibility purposes.

I also think linking CEEM projects (past and present) to their associated repositories would be really useful, especially for the “research output / reproducibility” class of repos. That could make the relationship between projects, papers, grants and tools much clearer for academic and external users.

[nick-gorman]

Thank for putting this together @dylanjmcconnell.

I also agree that one set of bespoke categories makes sense. And that the kind-of-active repos like NEMOSIS or Nempy are probably the hardest to categories. There is no active project of funding, but on the other hand they have had adhoc maintaince for serval years, so dormant doesn't seem the best fit either. Maybe Released - (continuing/adhoc volunteer support), or if badges are easy to make, have released Released as a wide category with the repo owner able make a custom badge with their own parentheses text to give the best flavour to what the support is like.

I like the idea of doing the badges and then using that as jumping off point to discuss maintaince further.

[dylanjmcconnell]

Thanks @nick-gorman - yeah definitely wasn't thinking "dormant" for either NEMOSIS or Nempy. Roughly had "Released - (limited support)" - in my mind (though very happy to change language and description for that - (these were just initial suggestions).. e.g.:

"Released - (limited support)" - Used by others; bug fixes & questions answered on ad hoc basis, no new features

Only push back re: custom badges would having some consistency across the org - and for the purposes of a common description at the org home (i.e. the table) - in my mind, the place for that more bespoke / custom information would be in a note? So maybe would look like this at a repo level:

Note

This project has no active project funding and is currently supported on an adhoc, volunteer basis

Or something

But as above, also open to having different categories (or collapsing some?) - maybe something better, that also deals with issue @EllieKallmier raised re: overlap between the WIP / Active research -

"Released - (supported)" - (instead of "Active research")
"Exploratory / WIP" - Prototype or work in progress (not stable, or recommended for use in production)
"Released - (limited support)" - Used by others; bug fixes & questions answered on ad hoc basis, no new features