Decide on an implementation naming convention
Closed this issue · 7 comments
One convention would be
algorithm-language[-optionalplatform][-optionaldescriptor]
For example:
mlkem-c-generic
mlkem-assembly-avx2-jasmin
mlkem-rust-libcrux
mlkem-c-stackoptimized
mlkem-c-aarch64
if someone is looking for an implementation how do they go about searching for it? as a target use of the implementation, will i be making my selection driven by the algorithm or by the language i prefer? What am i searching for?
We should optimize the naming convention for what intended users are going to search for. I don't have an answer one way or another.
Looked at a few other projects with SDKs, primary naming is language first.
I generally like the scheme.
But I'm not sure about the descriptor. That may get confusing quickly. Also one may think jasmin or libcrux are targets or describe special optimisations.
I have no data to back this up, but I can imagine the first criteria is capability - ie cryptography -> kem -> kyber (mlkem) as that's likely what I'm trying to add/change in my stack ? Language is often (not always) the next constraint. I have a primarily rust app, that's what I want to use. That being said I can imagine any of the other criteria - level of assurance, optimizations for performance, memory size, architecture are all really relevant too.
Overall I like the scheme proposed. ensuring some key criteria are in the name, somewhere, helps with filtering repos (but we shouldn't have too long names?). Especially as we get further right in the name I think we can be less prescriptive as we're trying to condense a lot into a small space!
We can also
- ensure we tag each repo appropriately ie using well-known tags where they exist
- ensuring the top level readme addresses the key search criteria early on (first 'page') to help people scanning through
- catalog our repos so that at least once here we explain the difference between the repos and address these characteristics, perhaps in a table. For example this could be auto-generated from a yaml file in each repo and added into the pqca repo in markdown (?mkdocs - or any other recommended way) to further improve searching
- test searchability in search engines
ensure we tag each repo appropriately ie using well-known tags where they exist
Agreed, may be worth it for the TSC to define a set of tags, labels, or other needed descriptors to support engineers searching for the right library.
ensuring the top level readme addresses the key search criteria early on (first 'page') to help people scanning through
Similar to above, if we are consistent in the minimum content and placement of such content within a README it makes it simpler.
catalog our repos so that at least once here we explain the difference between the repos and address these characteristics, perhaps in a table. For example this could be auto-generated from a yaml file in each repo and added into the pqca repo in markdown (?mkdocs - or any other recommended way) to further improve searching
YES. This can be on a website or in the TSC repo proper. TSC can pull together a matrix for those libraries that conveys or pulls some of this from the repository so there is a single central point when someone is trying to understand what options are available to them, if they are in development, stable, prod ready, etc.
test searchability in search engines
This may be some SEO work that can be passed to the PQCA staff to assist with.
We have a virtual hack day coming up next Tuesday (12). I presume this will involve create new repos, so I suggest going with the original proposal on naming. This is prior to tsc kickoff, and there may be repo renames later if required.
Closing as we adopted an initial naming scheme. No objects in 2024-06-20 TSC meeting