every now and then there’s confusion about the “mirage-crypto” opam package. It is not only for MirageOS, but works very fine in a pure OCaml environment (with whatever asynchronous event system you are using, or even with the bare OCaml stdlib). Please note that mirage-crypto originates from the excellent nocrypto package that David Kaloper developed.
That’s why I’m curious about your thoughts about renaming “mirage-crypto” to “crypto” (and dropping the “mirage-” prefix from the subpackages as well). Of course there’ll be some churn on reverse dependencies, but if the result is something that’s more approachable, I’m happy to go through the renaming.
Of course, such a new name, being it “crypto” or :“cryptography”, is also close to the very nice “cryptokit” package (maybe too close?). That’s why I’m asking… Please fill out the poll below, and if enough people pushed their vote, I’ll take a look what to do.
If you’ve any concerns, further discussions, or alternative names, please comment on this topic.
I have very little exposure to the OCaml ecosystem. My take on the name change, coming from other ecosystems.
The package naming itself is of little relevance, as long as it pops up during a cursory search for cryptography.
I don’t know of any large ecosystem consensus, but to me short, concise names like “crypto” /“cryptography” feel better suited for the ecosystem stdlib/base packages.
The transitiony period implies breakagas and forced updates across the stack, including confusion for users. (Does opam have a warning of “X deprecated use Y”?)
Documentation lookup becomes more confusing, “why can I only find 2 public topics on the crypto package”?
If this is with the purpose of better educating users about their gemeral usability, I think documentation and examples will have larger benefits.
Looking at the github repository, I see the readme title still points it out as “Cryptographic primitives for MirageOS”, while the project title does say its for general OCaml.
I would change the in-readme title to “OCaml cryptographic primitives library”, and structure the readme as
# "OCaml cryptographic primitives library"
"mirage-crypto is a small cryptographic library that puts emphasis on the applicative style and ease of use"
Table of current supported alghorithms, primitives, etc. For quick cursory glance at what features the user is looking for.
Single install line.
Example usage with stdlib and Lwt (seems popular in the ecosystem).
## "With MirageOS"
Example, specific noteworthy details about the runtime (?)
## thanks to the original project from which it was forked from
Build and other instruction could be moved to a HACKING file.
In my opinion that makes such a library more explorable and easier to get started with for newcomers, if those are the target audience for this change.
Its also worth considering that keeping mirage in the title could make others curios and discover MirageOS. That’s how I’ve learned about the project, and kept an interest to check it once in a while.
My immediate preference would be something not offered in the poll: keep the opam package as ‘mirage-crypto’, but use dune’s deprecated_library_name to offer both the old and new findlib package names for a few releases. Metadata churn is always enormous hassle unless there’s a few versions that work with the old and the new.
Interesting, I was not aware of that dune thingy. So it mentions also a deprecated_package_name, but I can’t find that in the docs anywhere.
From my perspective, surely that’s a breaking change. But I’d go as far as renaming not only opam packages, but as well findlib packages, and also the modules… So I guess the dune feature allow for the second and maybe the first, but not the third.
IMHO it’s important to allow for coinstallability so you can have a smooth transition (where you can have both the old and the new package in the same application). This means some duplicated assembly code as long as not all dependencies have been updated with the new package. But IMHO that’s fine.
Thanks for your suggestions. What opam has is the possibility of a post-message, displayed after installation of a package. Same for OCaml, there could be alerts at the modules so your build will print warnings about the deprecated modules (that may include how to do the upgrades).