Merge pull request #437 from pq-code-package/update-docs

Update documentation in preparation of the alpha release

Author: hanno-becker

.github/ISSUE_TEMPLATE/bug_report.md

@@ -1,38 +1,33 @@
 ---
 name: Bug report
 about: Create a report to help us improve
-title: ''
 labels: bug
-assignees: ''
-
 ---
 
+
+<!-- 
+
+Security reports
+
+DO NOT report security issues through Github issues - instead use Github's [private vulnerability reporting](https://github.com/pq-code-package/mlkem-native/security). 
+-->
+
+
 **Describe the bug**
 A clear and concise description of what the bug is.
 
-**To Reproduce**
-Steps to reproduce the behavior:
-1. Go to '...'
-2. Click on '....'
-3. Scroll down to '....'
-4. See error
+**Platform**: e.g., x86_64 Linux
 
-**Expected behavior**
-A clear and concise description of what you expected to happen.
+**Compiler**: e.g., gcc 13.2.0 (installed through nix)
 
-**Screenshots**
-If applicable, add screenshots to help explain your problem.
+**How to reproduce**
+Steps to reproduce the behavior:
+```
 
-**Desktop (please complete the following information):**
- - OS: [e.g. iOS]
- - Browser [e.g. chrome, safari]
- - Version [e.g. 22]
+```
 
-**Smartphone (please complete the following information):**
- - Device: [e.g. iPhone6]
- - OS: [e.g. iOS8.1]
- - Browser [e.g. stock browser, safari]
- - Version [e.g. 22]
+**Expected behavior**
+A clear and concise description of what you expected to happen.
 
 **Additional context**
 Add any other context about the problem here.

.github/ISSUE_TEMPLATE/feature_request.md

@@ -1,20 +1,31 @@
 ---
 name: Feature request
 about: Suggest an idea for this project
-title: ''
 labels: enhancement
-assignees: ''
-
 ---
 
-**Is your feature request related to a problem? Please describe.**
-A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+**Platform**: 
+Which platform does this concern?
+- [ ] platform independent
+- [ ] aarch64
+- [ ] x86_64
+- [ ] rv64
+- [ ] other
+
+**Issue category**:
+
+Which part(s) of mlkem-native does this issue concern:
+
+- [ ] core crypto: ML-KEM
+- [ ] core crypto: FIPS202
+- [ ] documentation
+- [ ] integration
+- [ ] CBMC
+- [ ] CI
+- [ ] Testing
 
 **Describe the solution you'd like**
 A clear and concise description of what you want to happen.
 
-**Describe alternatives you've considered**
-A clear and concise description of any alternative solutions or features you've considered.
-
 **Additional context**
 Add any other context or screenshots about the feature request here.

.github/pull_request_template.md

@@ -1,8 +1,21 @@
-[//]: # (SPDX-License-Identifier: CC-BY-4.0)
-<!-- Please give a brief explanation of the purpose of this pull request. -->
+<!-- 
+Security reports
 
-<!-- Does this PR resolve any issue?  If so, please reference it using automatic-closing keywords like "Fixes #123." -->
+DO NOT submit pull requests related to security issues directly - instead use Github's [private vulnerability reporting](https://github.com/pq-code-package/mlkem-native/security). 
+-->
 
-<!-- Any PR adding a new feature is expected to contain a test; the test should be part of CI testing, preferably within the ".github/workflows" directory tree. Please add an explanation to the PR if/when (why) this cannot be done. -->
+**Summary**:
+Provide a brief summary of your changes.
 
-<!-- Once your pull request is ready for review and passing continuous integration tests, please convert from a draft PR to a normal PR, and request a review. -->
+**Steps**:
+If your pull request consists of multiple sequential changes, please describe them here:
+
+**Performed local tests**:
+ - [ ] `lint` passing
+ - [ ] `tests all` passing
+ - [ ] `tests bench` passing
+ - [ ] `tests cbmc` passing
+
+**Do you expect this change to impact performance**: Yes/No
+
+If yes, please provide local benchmarking results.

.github/settings.yml

@@ -0,0 +1,66 @@
+[//]: # (SPDX-License-Identifier: CC-BY-4.0)
+
+# Building mlkem-native
+
+### Prerequisites
+
+To build **mlkem-native**, you need `make` and a C90 compiler. To use the test scripts, you need Python3 with
+dependencies as specified in [requirements.txt](requirements.txt). We recommend using a virtual environment, e.g.:
+
+```bash
+python3 -m venv venv
+./venv/bin/python3 -m pip install -r requirements.txt
+source venv/bin/activate
+```
+
+### Using `make`
+
+You can build and test **mlkem-native** as follows:
+
+```bash
+make quickcheck       # With native code backend (if available)
+make OPT=0 quickcheck # With C backend
+```
+
+To merely build test and benchmarking components, use the following `make` targets:
+
+```bash
+make mlkem
+make bench
+make bench_components
+make nistkat
+make kat
+```
+
+The resulting binaries can then be found in [test/build](test/build).
+
+### Using `tests` script
+
+We recommend compiling and running tests and benchmarks using the [`./scripts/tests`](scripts/tests) script. For
+example,
+
+```bash
+./scripts/tests func
+```
+
+will compile and run functionality tests. For detailed information on how to use the script, please refer to the
+`--help` option.
+
+### Nix setup
+
+All the development and build dependencies are also specified in [flake.nix](flake.nix). We recommend installing them
+using
+[nix](https://nixos.org/download/). To execute a bash shell with the development environment specified in
+[flake.nix](flake.nix), run
+```bash
+nix develop --experimental-features 'nix-command flakes'
+```
+
+### Windows
+
+You can also build **mlkem-native** on Windows using `nmake` and an MSVC compiler.
+
+To build and run the tests (only support functional testing for non-opt implementation for now), use the following `nmake` targets:
+```powershell
+nmke /f .\Makefile.Microsoft_nmake quickcheck
+```

BUILDING.md

@@ -1,4 +1,4 @@
 # SPDX-License-Identifier: Apache-2.0
 # Last matching pattern has precedence
 
-* @pq-code-package/pqcp-embedded-maintainers-aarch64
+* @pq-code-package/pqcp-native-maintainers

CODEOWNERS

@@ -1,6 +1,19 @@
 [//]: # (SPDX-License-Identifier: CC-BY-4.0)
-[//]: # (TODO Add contributing guide)
 
 # Contributing
 
-to be completed
+We welcome proposals to improve **mlkem-native**.
+In particular, we are interested to hear how you plan to use **mlkem-native** or what should be improved about **mlkem-native** allowing other projects to rely on it.
+If you have specific feature requests, please open an issue. 
+
+You can contact the **mlkem-native** team through the [PQCA Discord](https://discord.com/invite/xyVnwzfg5R).
+
+## Call for contributors
+
+We are actively seeking contributors who can help us build **mlkem-native**. If you are interested, please contact us,
+or volunteer for any of the open issues.
+
+## Call for potential consumers
+
+If you are a potential consumer of **mlkem-native**, please reach out: We're interested in hearing the way you want to
+use **mlkem-native**. If you have specific feature requests, please open an issue.