H5P Group should formally support Typescript for lib development

sppearson's picture
Forums: 

At least two members of the community have contributed decent types libraries to the cause, but I'm a little loathe to lean on those for anything someone's likely to inherit from me. What are the chances the organization will adopt one of them (or roll their own) in the near term?

otacke's picture

Hi!

Maybe you could elaborate on what you're suggesting? If someone wants to use Typescript or the type definitions that others have created (the one created by Sindre Bøyum for instance seems to be updated frequently), he/she can. H5P Group doesn not dictate what language/framework you should use for your code, e.g. for content types.

Best,
Oliver

sppearson's picture

If H5P published and maintained a types library along with the framework itself and illustrated and encouraged the use of TypeScript in the documentation (TS library project templates would also be terrific), it would make the framework more readily discoverable and generally encourage more rigor among the H5P developer community; I believe devs would also find it a better development experience overall and that it would lead to better quality community code over time, all of which would help drive greater adoption. Having the H5P Group itself publish and oversee their maintenance would give developers greater confidence that they could lean on those libraries in the long term.

At the end of the day, the Group _does_ dictate what language is used: ECMAScript. TypeScript's still the dominant strongly-ish "typed" language in that ecosystem, with a very low cost of entry. Making it a first-class citizen in the _H5P_ ecosystem just makes sense to me.

otacke's picture

I agree that a types library for H5P would be useful for those who would like to write content types or other client-side code that uses H5P in TypeScript. But there is. 

I kindly beg to differ about who should provide it though. H5P is an open source community project. H5P Group is neither a single source of truth and wisdom nor a caretaker with infinite resources for everyone's needs. It's absolutely fine IMHO if someone else (like Sindre Bøyum) creates and maintains a types library that other people use, or if someone else (like Sebastian Rettig) creates and maintains a port of the server-side H5P core to node.js that other people can use, or ... Why should it be H5P Group’s responsibility to provide all this? Sure, they could, but why re-invent the wheel? Why not use the solutions of others?

And, sorry, I completely fail to see how H5P Group dictates using EcmaScript. They do not use TypeScript themselves (and I believe they are rather going to jump onto the Javascript type annotations wagon, but maybe not even that), but how are they preventing you from using TypeScript? Why not get Sindre's type library, create something nice and contribute it to the community? Others have done it already and didn't feel hindered ...

Best,

Oliver 

sppearson's picture

I'd argue that most mainstream, significant open source JavaScript projects are now maintaining their types libraries as part of core. I think the H5P Group needs to adopt one for the same reason h5p-cli, h5p-php-library, and a host of other projects live in the organization's namespace. It implies a contract with their community: this is an important element of our platform's development ecosystem, and we're going to make sure it stays aligned with the development of the standard.

I'm not arguing that they're preventing me from doing anything. Nowhere did I make that claim. I'm just arguing that adopting a types library into core would show a commitment to broadening the appeal (and thus the long life) of the platform and ensuring it's given as much running room to grow as possible.

I'm trying to build libraries and content types that have legs and staying power for my organization and the educators that depend on us, and I want to make life as easy on whoever comes behind me and has to maintain what I've written as I can. For something as simple yet critical (in my world) as a types library (types are kinda' central to Typescript development, and are littered pretty liberally throughout my code), I'd prefer not to rely on a community project that largely depends on a single individual for its continuance; there's a lot of risk of great future pain implicit in doing so.

I'm admittedly biased, but I don't think it's an unreasonable suggestion. You clearly do. We can agree to disagree; that's perfectly fine.

(The comment re: ECMAScript was tongue firmly in cheek, by the way; not like they had a choice! ;-)

otacke's picture

Hey!

I don't think the suggestion is unreasonable, I personally - without expecting others to follow - just don't think that an "official" types library is required or that the lack thereof is a deal breaker for developers thinking about doing something with H5P. I have worked with Sindre's TypeScript types library and was pretty satisfied - and things it lacked were quickly added. 

On the one-man maintenance show: I have seen single persons handling repositories better than larger organizations, so while size may have some appeal as a rule of thumb: I can’t say that H5P Group couldn't do better, unfortunately.

But yes, we can agree to disagree.

Best, 

Oliver 

Sindre Bøyum's picture

Thanks for the free PR, Oliver! I do wish that the H5P project would expose TypeScript types as this definitely would make it easier for many devs to create content types or widgets, or even collaborate with H5P Group to improve the core.

I don't think that will happen very soon, which is of course perfectly ok! They decide for themselves what they want to work on. That is why I created the `h5p-types` project which I've seen makes it simpler to work with content types, especially for those of us who don't have years and years of experience with H5P.

I would share your fear that h5p-types is a one-man show if the dev behind it was a stranger, and there certainly is a bus factor there. I of course invite anyone to join the project and want to make it as accessible as possible, but until it's widely used and widely known, it's not very motivating for anyone else than me to work for it.

I have thought about moving the project to DefinitelyTyped, thus make it available on npm under `@types/h5p` or something like that. I feel that I would need a "go" from H5P Group before doing that and it would slightly increase the complexity for me.

Do you guys have any thoughts about my strategy here? Would you do things differently?

For what it's worth: I watch the most important of H5P Group's repositories and try to implement new changes in less than a week after it was commited, however I of course can't say how long I'll find this interesting to do.

otacke's picture

expose TypeScript types as this definitely would make it easier for many devs to create content types or widgets, or even collaborate with H5P Group to improve the core.

How?

Sindre Bøyum's picture

The thing that has brought my teams and I into tears and hours of debugging the most times is that H5P isn't very well documented. Not all types and classes have documentation at all, and some that do have wrongful documentation. I've missed the code completion, spell checker and suggestions that many other libraries come with. In the beginning, constantly using a debugger or console.logging every variable we wanted to access was very tiring and we would have changed technologies if H5P was not a requirement. 

Nowadays I'm much more versed in H5P and know my way around library.json, semantics.json and everything that comes with them, but my H5P Quality of Life plugin that I made for VS Code still helps me when writing these JSON files. Its JSON schemas are in turn generated from the h5p-types library.

The types helps with H5P's weird quirks. I'm sure no-one would guess that having a group with only one field in it would in practice make that group invisible? The `InferParamsFromSemantics` (https://h5p-types-docs.vercel.app/types/InferParamsFromSemantics.html) type utility takes care of that. Who would know of `H5P.isEmpty` if it wasn't part of the `H5PObject` type in `h5p-types`? H5P is huge (in a good way!) and there is so much functionality that it takes years to fully grasp without documentation. The reason I know so much about H5P now is that I've read through the source code three or four times. No one can be expected to do that even once.

I think part of my wish for a H5P core type library comes from the fact that most other libraries provide types and devs today are used to getting that help from the IDE. If that wish is not shared, that's perfectly ok, I just want my project not to die because I do see that it helps people.

sppearson's picture

Thank you, Sindre; my thoughts exactly. It's table stakes now, as far as I'm concerned.

And thank you, too, for all of the effort you've put into your tooling projects. They've been tremendously helpful as I've struggled up that learning curve.

otacke's picture

I'd like to repeat: I don't dispute the use of some h5p types library. If you (whoever reads this) will check my previous post, you will notice that I even hinted to Sindre's library). But I dispute that this must (or should) be the responsibility of H5P Group.

 

Yes, the official documentation is insufficient to put it nicely. Changes to the API or maybe new functions should ideally be announced by the H5P core team in some way or another. But they don't. So, what are the options? Wait, nudge, complain? Or take action oneself? Probably a combination of both ideally, but I clearly prefer the emphasis on the latter.

 

Today's world doesn't force us into the role of passive petitioners. "Mistrust authority - promote decentralization." In other words: If you lack something in an open source project, then use the empowerment that you have, create a solution yourself, share it, find others to jump on the waggon. It works. There's no need for a caretaker. Yes, that takes some effort that you may not be willing to invest, maybe because you are merely working on some (closed) project as a contractor, want to get shit done to get paid, and don't really care about the project and its community and about giving something back - and open source may just be a nice way of not paying for things for you (that's not an accusation here, Sindre, h5p-types shows something else; it's a general remark, because I experienced that attitude multiple times already and know it's not completely off).

 

That's just my two cents. If you cannot work that way and expect everything from some "offical central authority" (for whatever reason: assumed better quality, assumed higher response rate, assumed higher speed, having one single entity to blame, ...), then you now know that at least one other person doesn't think that way.

sppearson's picture

otacke, someone who doesn't care wouldn't bother carrying on an extended dialog about this. I think I'm making a valid and reasonable suggestion, and I don't feel an adversarial tone is at all justified or helpful. I've read everything you've written carefully; please return the favor. Thanks.

sppearson's picture

I think we're talking past each other, otacke.

I'm not saying the Group has to actually build the thing -- please go back and read my original post. But as the organization purportedly steering the project, yes, the Group has some responsibility, here, for structuring things to ensure the larger project's continued relevancy and vitality. One of those responsibilities to my mind -- and perhaps their chief responsibility --  is nurturing a healthy development ecosystem. My contention, humbly, is that Typescript language support should be considered a core element of that ecosystem.

A types libary is a simple -- but very critical -- requirement for that developer base. Whether Group members actually write the code or merely give their blessing and guidance to a community effort to do so in the Group's name is all the same to me. There's no good reason to have a bunch of little, uncoordinated community efforts sitting out there in the registry, in my opinion.

That's how the best open source projects work, imho: the governing body identifies important work to be done, asks for community members who are interested to volunteer to tackle the work, and helps steer their efforts. There are already community members clearly interested. They wouldn't even have to start from scratch, thanks to Sindre et al.

I'm very happy to contribute to that effort. But, yes, if they are going to do something in the name of the entire community, the Group has to bless and help steer it. 

I'd be happy to make the suggestion via Github issue (I'm just not sure what project to do so in, since it seems all the core JS front end code's maintained as part of the two PHP lib projects) or another channel.

 

otacke's picture

I am deeply sorry if I misread your posts or interpreted something into them that you did not mean to say. I fully agree with the notion that H5P Group needs to take a stronger stance regarding establishing an environment nurturing the open source side of H5P in general, and that is not a secret. And I am going to shut up now :-)