# Using Github to share openEHR content **Category:** [REQUESTS](https://discourse.openehr.org/c/tool-requests/95) **Created:** 2023-04-17 13:33 UTC **Views:** 940 **Replies:** 30 **URL:** https://discourse.openehr.org/t/using-github-to-share-openehr-content/3863 --- ## Post #1 by @ian.mcnicoll As well as CKM, quite a number of implementers/ modellers make their openEHR content available via GitHub. @erik.sundvall @vanessap @bna amongst others However keeping track of where those repos live or whether they contain clinical models vs. other software artefactsm is quite challenging.. I have two proposals 1. Perhaps setup some sort of registry of GH accounts with public openEHR content repos. 2. Tag those repos which explicitly have archetypes or template with something like 'openehr-content', so that they can be clearly identified.GitHub Topics seems a good fit for this as it is readily searchable https://github.com/topics e.g. https://github.com/freshehrteam/Salford_PROM --- ## Post #2 by @Seref A simple, yet effective way is following the tradition of 'awesome X' repositories. As in https://github.com/krispo/awesome-haskell just google awesome bla and you'll hit a repo. Assuming bla is a programming language, tech concept etc. Very common with frameworks, libraries etc. then you put the repo link in your documentation or some other visible/central location. --- ## Post #3 by @ian.mcnicoll Part of my thinking was to make it easy by allowing people to publish their accounts on such an 'awesome' page but make that largely self-managing by 'tagging' any content-related repos. You can then use the GitHub api / search box or their new GH CLI tool ``` ian@MacBook-Pro hse-docs % gh search repos --topic=openehr-content Showing 2 of 2 repositories NAME DESCRIPTION VISIBILITY UPDATED freshehrteam/Salford_PROM public about 24 minutes ago freshehr/nhs-pgx NHS Pharmacogenetics project private about 2 months ago ``` You may not see the private repo --- ## Post #4 by @erik.sundvall Sure, just tell us what tag to use and we'll do our best to tag it (and we hope that somebody else will write that script for outputting links on a webpage). --- ## Post #5 by @ian.mcnicoll [quote="ian.mcnicoll, post:3, topic:3863"] `openehr-content` [/quote] So the **Topic** to add to any repository that contains openehr archetypes, templates or gdl is `openehr-content` @erik.sundvall -instead, or as well as outputting the links to a web-page, it might be worth considering a tool that would parse the contents of a repo and create a Markdown formatted list of contained archetypes and templates (along with their human concept names. That can be added to the repo README which I understand to be searchable in GitHub. --- ## Post #6 by @joostholslag Great idea. And let’s link there from openEHR.org national CKM page. --- ## Post #7 by @rong.chen Here is our open source github repo for clinical decision support models, https://github.com/openEHR/gdl-guideline-models, based on openEHR archetypes and GDL/GDL2 guidelines. Besides tags, it might be good to standardize the repo structure too, e.g. archetypes, templates etc. Our own CKM follows a pre-defined structure to facilitate batch-import of these models. --- ## Post #8 by @ian.mcnicoll I agree about a basic structure, which I think also needs to separate local content from remote non-owned archetypes. I'm not so bothered about separate folders for each archetype class So ? ``` archetypes local com.freshehr org.ucp.london remote org.openehr uk.org,apperta templates local com.freshehr org.ucp.london remote org.openehr uk.org,apperta gdl valuesets mappings ``` --- ## Post #9 by @rong.chen Looks good as a starting point for sure. Seems to be a great topic to follow up on the tooling SEC Working Group. --- ## Post #10 by @ian.mcnicoll Could everyone who is keen on the idea and already publishes openEHR content on Github, add `openehr-content` as a "Topic" to any repos and let me know so that I can test that we are picking them up in GH searches. https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/classifying-your-repository-with-topics --- ## Post #11 by @damoca Isn't `openehr-content` a bit generic if it is to be used only for archetypes and templates? Maybe something like `openehr-models` is more descriptive. And then we can also have `openehr-tools` for implementations, to say something. But this is just a though, I don't want to enter into defining full ontology of openEHR topics :sweat_smile: --- ## Post #12 by @ian.mcnicoll I'm definitely up for other suggestions - I wanted to include valuesets, GDLs, AQL etc i.e. anything that is not 'code' as such which was why I did not want to use 'models' maybe 'openehr-care-content'? Any better suggestions? --- ## Post #13 by @damoca Maybe a bit too formal, but what about `openehr-knowledge-resources`? --- ## Post #14 by @joostholslag I just added this topic to a few of the repos I have access to. I think it’s hard to come up with something much better than ‘openEHR-content’. So could we settle on that for now? @sebastian.garde could you do this for CKM mirror please? @rong.chen could you do so for the GDL repos? @SevKohler could you do so for the omocl and fhir-connect repos? @vanessap could you do so for your repos? @Pete_Bouvier if we get this going, would be good to add this trick to the openEHR website page that lists CKMs. --- ## Post #15 by @ian.mcnicoll We do this routinely now for all our GH-based repos. @erik.sundvall @amanda.herbrand @Paulmiller Could we get CBP support for this? --- ## Post #16 by @siljelb Just as a heads-up, we're looking at moving all our public Norwegian openEHR related repos to Codeberg.org due to ... `*waves hands vaguely at the state of the world*` We'll definitely add the topic(s) there though. --- ## Post #17 by @ian.mcnicoll Unfortunately topics are github specific afaik . Yhe whole point was to make the artefacts essily discoverable through gh search. Im not aware of any generic git approach. Also the openehr AD only supports github for read write, git is supported but readonly. --- ## Post #18 by @siljelb [quote="ian.mcnicoll, post:17, topic:3863"] Unfortunately topics are github specific afaik . Yhe whole point was to make the artefacts essily discoverable through gh search. Im not aware of any generic git approach. [/quote] That's why I'm mentioning it here, tbh. Nothing's finally decided yet, but since we're consolidating a number of repos from different organisations and personal accounts soon anyway, it only makes sense to make the move away from a US based service while we're at it. [quote="ian.mcnicoll, post:17, topic:3863"] Also the openehr AD only supports github for read write, git is supported but readonly. [/quote] Ah, that's an important consideration for our planned procurement. Thanks! --- ## Post #19 by @erik.sundvall [quote="siljelb, post:18, topic:3863"] [quote="ian.mcnicoll, post:17, topic:3863"] Also the openehr AD only supports github for read write, git is supported but readonly. [/quote] Ah, that’s an important consideration for our planned procurement. Thanks! [/quote] I think at least the on-prem AD supports GIT in general not only Github, but logins etc might be trickier to set up fo admins and adjust to for end users instead of just using Githubs's/Microsofts's. @borut.fabjan or somebody else at Better might know details. @siljelb a first step to reduce reliance on US services could be to make sure that you set up some automatic copying of Github content to som non-US GIT provider. If a lot of openEHR users start using a particular non-US GIT-service, then I guess it could be worthwile for openEHR to set up a second CKM-mirror feed from CKM to that other GIT-service instead of only to Github. --- ## Post #20 by @richard.kavanagh [quote="erik.sundvall, post:19, topic:3863"] AD supports GIT in general not only Github [/quote] My archetype viewer project is not dependent on GitHub it could source archetypes from almost anywhere. That said, it is currently running on AWS so that does dodge the US issues. --- ## Post #22 by @SevKohler Done thank you for reminding me. --- ## Post #23 by @ian.mcnicoll Yes locally hosted AD does support full readwrite access but the problem is that afaik, there is no standard approach to searchable metadata akin to Github. The idea was that anyone creating opnehr model content coukd very easily make that repo searchable. Ive not so far found anything comporable though interestingly the forked norwegian ckm repo does serm have a topic still attached @siljelb . I can't see any way to add them in Codeberg but perhaps this is work in progress. --- ## Post #24 by @siljelb [quote="ian.mcnicoll, post:23, topic:3863"] Ive not so far found anything comporable though interestingly the forked norwegian ckm repo does serm have a topic still attached @siljelb . I can’t see any way to add them in Codeberg but perhaps this is work in progress. [/quote] It took me a while to find it too: ![image|584x500, 75%](upload://yGEAHndPcUFXnvzMUASct6eKKEd.png) --- ## Post #25 by @bna [quote="ian.mcnicoll, post:23, topic:3863"] The idea was that anyone creating opnehr model content coukd very easily make that repo searchable [/quote] I will bring in some other Ideas around this. Recently I have explored how to make multi-repo documentation using Antora. It seems promising so far. The idea is to be able to write project specific documentation in each repo and then be able to aggregate and present one web page with all information searchable and readable. For Templates I use the adciidoc output from AD. This is Inspired by the work we did @ian.mcnicoll . We might be able write some software to automate the docs from openEHR artifacts.. IMHO this will be important to be able to share our modelling projects around the world. I think @SevKohler also have some ideas on s project index for transparency. I would love to se some joint efforts on this. First we will, as @siljelb mentions, try out how to share inter-regional projects in Norway. --- ## Post #26 by @ian.mcnicoll Can we come back to the original topic? I'm not wedded to openehr-content . I'd be happy with openehr-knowledge-resources. The nice thing about Github search (I know!!) is that all that need to happen is for someone to tag the repo with that topic ands it becomes globally searchable, including via the Github API. That allows folks to easily contribute peer-produced archetypes and templates with minimal overhead, especially if you use a standard repo template like https://github.com/freshehrteam/_-freshEHR-project-folder where the topic label can be preset. @bna - I'm really interested in this Antora idea. We use that along with our variant of the asciidoc builder to build Implementation guidance for a client. I'm also interested in how we might make use of the FHIR IG build stack. I'm very open to alternative ideas on how to easily share 'peer' content but so far I cant see anything that matches the simplicity of using Github topics. @siulje - it does look as if Codeberg has imported the GH topic but I could not find any way to edit that or add one. Also Codeberg for now does not have an API that would allow search. Looks very interesting however. Correction - I found how to edit Topic in Codeberg. You have ot have code there first --- ## Post #27 by @ian.mcnicoll Nice -we can search Codeberg for openehr-knowledge-resources topics ![image|690x378](upload://zb3Q5S28Yj29uM8gMSyGyS9TQOe.png) even better if it was api-backed so we could combine with GH search. ah!!! https://codeberg.org/api/swagger#/repository/repoSearch --- ## Post #28 by @ian.mcnicoll Can we agree on `openehr-knowledge-resources` @bna @vanessap @siljelb @Paulmiller @LindaAulin @amanda.herbrand @sebastian.garde Would it help to have that endorsed by e.g CPB ? Also do you think we can agree a standard-ish folder structure as per https://github.com/freshehrteam/_-freshEHR-project-folder --- ## Post #29 by @siljelb `openehr-knowledge-resources` makes sense to me, but I think we should define it. Does this mean archetypes and templates in their original format, or also OPTs, forms, and other downstream artefacts? I also agree it would be useful to have a common folder structure, but I'd suggest something like this: Required: ``` src/ # source artefacts like archetypes, templates, aql files, and source code for logic/scripts/etc build/ # any downstream artefacts like OPTs, form packages, compiled/interpreted code, etc doc/ # documentation for the repo ``` Optional: ``` test/ # well, tests data/ # sample data dep/ # any dependencies tools/ # any qol tools etc LICENSES/ # for when a single LICENCE file isn't enough ``` Ref: [GitHub Repository Structure Best Practices | by Soulaiman Ghanem | Code Factory Berlin | Medium](https://medium.com/code-factory-berlin/github-repository-structure-best-practices-248e6effc405) Edit: This is what our current repos look like, but we're looking at making changes to clean it up like in my suggestion above: [openEHR-no/templat-repo: Templat for å opprette nye repositorier. - Codeberg.org](https://codeberg.org/openEHR-no/templat-repo) --- ## Post #30 by @marcusbaw [quote="Seref, post:2, topic:3863"] A simple, yet effective way is following the tradition of ‘awesome X’ repositories [/quote] I realise I'm late to this discussion but I just wanted to strongly +1 @Seref's suggestion here simply because it works for **anything** that has a URL/URI, not just some content in some code forges. GitHub tags are 'sort of OK I guess', and I can see a decent amount of thought has already gone into the plan to use `openehr-knowledge-resources`. The problem is that (as the Norwegian team have done) if someone uses *another* code forge site (Bitbucket, Codeberg, GitLab, whatever) then: * We are reliant on there being a 'repository tag' feature in all possible code-forges, and that it is **searchable**. (I guess this is quite likely to be true for most code forges though) * It soon becomes necessary to search **all** of those forges in order to get a comprehensive list of all resources. * If someone, anywhere in the world, on any code forge, decides to inappropriately tag a thing with `openehr-knowledge-resources`then that repo will inappropriately show up in your search results and there's nothing you can do about it. An `awesome-openehr`repository has the following advantages: * Total simplicity and robustness - it can list **any** resource **anywhere** as long as it has a URL/URI, even if **not** in a code forge (eg it is on a simple web file server), or if the code forge doesn't have tagging. * The list can be **curated** so we can trust the content of it. Managing it in Git-tracked Markdown and pushing it to a codeforge means we get revision control for free as well, and the full commit history. * OK, so I admit the fact it needs to be **curated** is also a **disadvantage** since *somebody* has got to do this, but firstly I don't see this stuff changing on a very frequent basis, so it's not a huge task, and secondly Merge Requests/Pull Requests are our friend here, those wishing to include new content can submit a PR and the curator simply accepts if appropriate. * It is *probably* not that hard to parse the URLs out of MD/text if automated/CLI tools are desired, as per @ian.mcnicoll's `gh` CLI search. (We are eventually going to need an openEHR Knowledge Artefacts Package Manager of some kind anyway, and at that point we might want to publish more structured metadata about each artefact, but that feels a way off if we don't yet have a canonical folder structure in widespread use. There's nothing stopping us from doing **both things** - tags **and** an awesomelist - but I'd reckon the Markdown/plain text awesomelist version would be more likely to remain canonical - as 2025's frankly bonkers geopolitical daily comic strip shifts the perception of using GitHub and other US-based services. --- ## Post #31 by @joostholslag Yes let’s do both. My main concern is the governance of what is ‘awesome’. If it’s really awesome it should probably be in CKM anyways. Other than that it’s super arbitrary. We could make sections in the list off course. And even automated additions based on GitHub/code berg tags, assuming it’s available over api (codeberg doesn’t support this I understood?). --- ## Post #32 by @siljelb [quote="joostholslag, post:31, topic:3863"] assuming it’s available over api (codeberg doesn’t support this I understood?). [/quote] It does, Ian posted the link to the API doc: [Forgejo API](https://codeberg.org/api/swagger#/repository/repoSearch) --- **Canonical:** https://discourse.openehr.org/t/using-github-to-share-openehr-content/3863 **Original content:** https://discourse.openehr.org/t/using-github-to-share-openehr-content/3863