Improving Developer Experience

[fkleedorfer]

I have been thinking about improving developer experience for users and contributors of QUDT. I bet some community members have as well - maybe we can come up with one or two low hanging fruits that we can then work on?

In answers to this I'll post individual things I've noticed, and maybe possible ways of addressing them. Please comment and post your own!

[fkleedorfer]

Same Tools for Everyone

Problem: Currently, a contributor cannot clone the repo, make some changes, and then produce a modified set of QUDT files that would be identical to an official QUDT release built off that state of the repo.

Why is that a problem: There is no way of verifying the effect of your changes to the result of the algorithm. You'll have to wait for the next release, or (in most cases) for a rewiew of the PR by someone who can run the algorithm and inform you of any problem that might arise.

Cause:: This is due to the fact that making a release involves running some code that is not part of the public codebase.

Fix:

Option 1: the not-so-public tools for building the release require a development environment that cannot easily be replicated. It is certainly possible to port all the transformations to a more general form (pure SHACL-AF, for example), but there is still a burden on the contributor to set up some development environment to execute that.

Option 2: (related, but different) Port the 'algorithm' to something that can be run in a github action, and run it in a github action on every push to a PR. Add a github action for SHACL checks, and fail the build if there is a problem.

[fkleedorfer]

I suspect it could be ported to shacl-AF, which is supported by jena command line tools. Great to have the pointers here.

[fkleedorfer]

With the restriction that shacl af does not allow delete. Hmmmm...

[steveraysteveray]

If that's the only obstacle, we could have a shell script that just goes in and deletes all the qudt:applicableUnit lines in the file before handing it over to a SHACl reasoner.

[fkleedorfer]

Agreed - I'm sure that there are ways around this limitation.

[fkleedorfer]

This has been fixed. The project now uses maven and github actions, the appliacable units algorithm is exectued as part of the build process.

[fkleedorfer]

Automated SHACL checks

Problem:: When you contribute, you fork, make some changes, and make a PR. Then, the maintainers will look at the contribution and might request changes. Often, it will be something that is caught during SHACL verification. Having that depend on high contributor engagement or maintainer activity causes a bottleneck.

Why is that a problem: Such checks should be cheap to run for a contributor, otherwise, only few will do it. More work for maintainers, longer turnaround times for additions and bugfixes.

Cause:: It is a variant of the 'Same tools for Everyone' problem. Not everyone knows about shacl, not everyone has the environment to even run the checks.

Fix: A github action that runs the SHACL validation on each push to a PR.

[fkleedorfer]

I believe jena command line tools would do the job, but you'd have to preprocess the QUDT ttl files, because I the owl:imports statements won't cause jena to load more local files. It's possible that there is some trick to it but one might just as well dump all the relevant ttl files into one. (@steveraysteveray might be able to advise which ones are relevant) Then use the jena shacl verify on the combined data file with the right shacl ttl files (again, @steveraysteveray might know more which one(s)). A bit of bash scripting on top of that to postprocess the results and make the action fail or succeed.

[steveraysteveray]

With the exception of the applicable units algorithm I just mentioned above, this sounds like a good approach. I'm not a proficient bash script writer, though, nor a yaml coder, but I am available to help on the Turtle/SPARQL/SPIN side, and on the imports closure side, if needed. The full imports closure graph is described in our README here.

[jimkont]

another (easy) approach could be to create a small Java (maven) project in a subfolder that will define JUnit tests with all the constraints that need to be enforced. Using Jena it will be easy to validate that all files are valid RDF, validate specific files against shacl rules as well as more custom logic.
This project could also provide some utilities for e.g. preparing a new release or other maintenance tasks that are needed occasionally.

I agree that CLI scripts are simpler but using actual code can provide more flexibility

[fkleedorfer]

@jimkont the suggestion of a maven project in a subfolder leads us to the Use a build tool? question. I Agree, that would be one way to do it.

[fkleedorfer]

This has been fixed. The project now uses maven and github actions, the SHACL checks are exectued as part of the build process.

[jhodgesatmb]

These are valid issues. I do not even know how to run the checks so I don't. That means that Steve is holding the bag for all PRs and that is just wrong. So, if for no other reason than that Steve should be able to have all this time back we should try to find a way to achieve these solutions.

…

On Tue, Jun 25, 2024 at 6:50 AM steveraysteveray ***@***.***> wrote: @fkleedorfer <https://github.com/fkleedorfer>, I agree with the goal here. If we can build a github action that doesn't cost us $ with GitHub, I would welcome such a solution. — Reply to this email directly, view it on GitHub <#942 (reply in thread)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AATQRWOKSUEYM5YFEY36YB3ZJFYTJAVCNFSM6AAAAABJ3ZXL2CVHI2DSMVQWIX3LMV43SRDJONRXK43TNFXW4Q3PNVWWK3TUHM4TQNZSGAZTE> . You are receiving this because you are subscribed to this thread.Message ID: ***@***.*** com>

-- Jack

[fkleedorfer]

Generate properties wherever possible

Problem: Some unit/quantitykind properties are very regular, such as label, symbol and ucum code. Not rarely, mistakes are found and corrected in those properties.

Why is that a problem: Creating and maintaining ~ 6000 properties by hand has been (and will continue to be) a lot of work spent if there is a way to automate it

Cause: There is no obvious way to automate generating these properties, and there is no concept of a build process in the QUDT repo that would allow for generating anything really.

Fix:: The unit IRI localnames follow strict rules, and QUDTlib has used this property to add a tree of 'factor units' for each unit. This tree can be used to generate labels, symbols and ucum codes for any derived unit based on their factor units. The Possible solution thus would be to add these properties to the non-derived units only (and to any derived units for which these properties are irregular), and to use QUDTLib to generate them wherever they are missing.

[fkleedorfer]

For derived units, the dimension vector can also be generated using QUDTLib

[steveraysteveray]

This all sounds promising. Do you think a QUDTLib routine can be invoked to directly edit the units file, rather than just making suggestions? Are we ready for that?

[fkleedorfer]

I am not sure, but I think we should discuss it. Here is how it might be done:

QUDTLib performs java/typescript code generation based on the QUDT files during its build process. The resulting programs offer said functionality (generate labels, symbols, dimension vectors). Thus, in order to be used for generating properties for, say a PR, QUDTLib would have to be built based on the last commit of the PR, or it is not guaranteed to incoporate all the latest changes. In most cases, this will turn out ok, but there are a number of ways in which this can go wrong. For example, if a conversionMultiplier is changed in the PR to QUDT that occurs in a QUDTLib unit test, that test will fail, causing the build to fail.

So, in a (still to be designed) QUDT build, one step could be the build QUDTLib, and then to use it to generate the properties.
Advantages:

• generating properties, potentially many more than we now have, because labels can be generated for derived units in many languages
• properties can be made to be very regular (always use the same character for multiplication and division, for example)
  Downsides:
• any present bug or future regression in QUDTLib degrades QUDT quality.
• the build process is quite complex: as this requires a QUDTLib build, not a versioned QUDTLib artifact, ithe approach would require including QUDTLib as a git submodule in QUDT.

[fkleedorfer]

Rigorous checks for conversionMultiplier/conversionOffset/value properties

Problem: conversion factors, offsets and constant values are part of QUDT, but there is no quality assurance for them.

Why is that a problem: There is a disclaimer, but people will use these values, possibly for important stuff, and so they had better be correct.

Cause:: It has not been a priority to provide rigorous checks. It is also not obvious how it would have to be done.

Fix: Not obvious. QUDTLib provides half a solution for derived units: the conversionMultipliers are computed based on the factor units and compared with the conversionMultiplier property. If there is a significant difference, it is reported as an error. These checks could be incoprorated in QUDT, but they would not catch any mistakes in non-derived units.

So, Question: Which sources could be used to compare the values with (which we are sure are not getting their values from QUDT)?

[steveraysteveray]

Agreed. This is the best source. Perhaps @fkleedorfer can figure out how to get the right data out of it to be able to compare our conversion multipliers using some Java routines and his unit factoring code.

[fkleedorfer]

Does not cover all of QUDT but the most relevant part of it for any practical purposes. Anything comparable from the anglo-american part of the world for the imperial system? (NIST comes to mind)

[steveraysteveray]

I'm afraid that NIST does not provide any machine-readable service for this, as far as I know.

[fkleedorfer]

We only need the values. A pdf might suffice.

[steveraysteveray]

Ah, I thought you were pursuing ways to automatically validate going forward. But at least for a single validation pass, see page 219 in https://www.nist.gov/system/files/documents/2019/12/03/00-20-h133-apdxE_final-17.pdf. @ralphtq has his newly minted pdf interpreter that might be able to turn all this into RDF.

Also, for the constants defining the SI: https://www.nist.gov/si-redefinition/meet-constants

[fkleedorfer]

Use a build tool?

Problem: All Issues brought up so far require or aim at some kind of build automation. There currently is none.

Why is that a problem: Anything that needs to be done manually will cause errors, bottlenecks and dependency on individuals

Cause: Most programming languages/frameworks come with a variety of build tools, and most projects use one. However, this is an ontology project, inherently independent from programming languages, and therefore, it is not obvious what should be used. That is probably the reason why none is in use.

Fix: Choose one build tool that the community can live with and refactor the project so it uses that tool. Bonus: github actions become easier to make and maintain because they might only need to run some build targets

So, question: What would be your criteria for choosing a build tool, and which one, if any, should it be?

[steveraysteveray]

I support this, but have little experience, so I defer to you and others to lead the way!

[fkleedorfer]

@jimkont suggests a maven project in a subfolder. Cross-linking that here because it is relevant to this question as well.

[fkleedorfer]

I'll start with some criteria OTOH:

A good build tool is one that

• people in the community already know
• makes it easy to run high quality RDF tools for formatting, SHACL validation, SHACL AF, SPIN(?), java/js programs (->QUDTLib, if we want to use it),
• does not require us to change the folder structure too much (would we be ok with changing that structure?)
• allows for automating the release process (RDF file munging, zipping, etc.)

[fkleedorfer]

This has been fixed. The project now builds with maven.

[jhodgesatmb]

If a build/testing environment can be invoked at the command line then it can be invoked on any schedule. Gitlab can invoke scripts during checkin and push. I am not familiar with current build/test environments.Jack Hodges, Ph.D.Arbor StudiosOn Jun 28, 2024, at 7:16 AM, Dimitris Kontokostas ***@***.***> wrote: another (easy) approach could be to create a small Java (maven) project in a subfolder that will define JUnit tests with all the constraints that need to be enforced. Using Jena it will be easy to validate that all files are valid RDF, validate specific files against shacl rules as well as more custom logic. This project could also provide some utilities for e.g. preparing a new release or other maintenance tasks that are needed occasionally. I agree that CLI scripts are simpler but using actual code can provide more flexibility —Reply to this email directly, view it on GitHub, or unsubscribe.You are receiving this because you commented.Message ID: ***@***.***>