Project Documentation Standards

[franziskuskiefer]

What's the documentation all projects should provide? We should aim at least for the Readme.md of all projects to have a similar structure and there should be a common set of information to be found on all of them.

Here's a rough idea of what that could go on there

• getting started
• status
• security
• Verification status label
• Verification status table (with common column names across all projects)
• Performance (common layout across all projects, with comparable numbers)
• FAQ

[mkannwischer]

This was discussed during the 2025-08-07 TSC meeting.

I propose we settle on the things that have to be present in the README and leave the form up to the project.

Some small adjustments on list proposed by @franziskuskiefer:

• Getting started
• Status (recommended for production/in development/etc)
• Constant-time goals / properties - this is currently called "Security" in mlkem-native and libcrux
• Verification scope (which parts of the code are covered and which guarantees are obtained)
• Performance (how to reproduce - speed+memory+binary size)
• ACVP testing coverage

Can @pq-code-package/pqcp-tsc please comment on this if you are fine with this list or you would like to adjust something.
I would like to vote on this during the 2025-09-04 TSC meeting.

[mbbarbosa]

Looks good to me.

[franziskuskiefer]

lgtm

[tfaoliveira]

Looks good

[mkannwischer]

@hanno-becker @jakemas @mjosaarinen @praveksharma, if one of you agrees to the proposal above, we will start requiring it from all projects.

I'd then open issues in each project. Once the standards are met (which may already be the case for some projects), the issue can be closed.

[hanno-becker]

Looks good

[mkannwischer]

I have opened issues in each sub-project. Here is the list to track:

• Meet PQCP Project Documentation Standards mlkem-native#1289
• Meet PQCP Project Documentation Standards mldsa-native#634
• Meet PQCP Project Documentation Standards slhdsa-c#38
• Meet PQCP Project Documentation Standards rust-libcrux#6
• Meet PQCP Project Documentation Standards mlkem-libjade#4

Please try to complete this issue by the next PQCP TSC meeting (2025-12-04).