From 61d5e186bae6974c1456af7b43ed3757a838bdf8 Mon Sep 17 00:00:00 2001
From: "Matthias J. Kannwischer" <matthias@kannwischer.eu>
Date: Thu, 21 Nov 2024 09:47:19 +0800
Subject: [PATCH] Update documentation in preparation of the alpha release

Signed-off-by: Matthias J. Kannwischer <matthias@kannwischer.eu>
Signed-off-by: Hanno Becker <beckphan@amazon.co.uk>
---
 .github/ISSUE_TEMPLATE/bug_report.md      |  39 +++---
 .github/ISSUE_TEMPLATE/feature_request.md |  27 ++--
 .github/pull_request_template.md          |  23 +++-
 .github/settings.yml                      |  18 ---
 BUILDING.md                               |  66 +++++++++
 CODEOWNERS                                |   2 +-
 CODE_OF_CONDUCT.md                        |   6 -
 CONTRIBUTING.md                           |  17 ++-
 GOVERNANCE.md                             |   6 -
 README.md                                 | 156 ++++++++++------------
 RELEASE.md                                |  28 ++++
 SECURITY.md                               |   8 +-
 SUPPORT.md                                |   6 -
 docs/images/mlkem_native.png              | Bin 0 -> 13534 bytes
 scripts/ci/lint                           |   4 +-
 scripts/format                            |   2 +-
 16 files changed, 243 insertions(+), 165 deletions(-)
 delete mode 100644 .github/settings.yml
 create mode 100644 BUILDING.md
 delete mode 100644 CODE_OF_CONDUCT.md
 delete mode 100644 GOVERNANCE.md
 create mode 100644 RELEASE.md
 delete mode 100644 SUPPORT.md
 create mode 100644 docs/images/mlkem_native.png

diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md
index f3d5c415e..c6de62fd4 100644
--- a/.github/ISSUE_TEMPLATE/bug_report.md
+++ b/.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.
diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md
index 11fc491ef..e0d799c23 100644
--- a/.github/ISSUE_TEMPLATE/feature_request.md
+++ b/.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.
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
index 92957f2a6..e26f6aaed 100644
--- a/.github/pull_request_template.md
+++ b/.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.
diff --git a/.github/settings.yml b/.github/settings.yml
deleted file mode 100644
index f85205f81..000000000
--- a/.github/settings.yml
+++ /dev/null
@@ -1,18 +0,0 @@
-#
-# SPDX-License-Identifier: Apache-2.0
-#
-
-repository:
-  name: template-code
-  description: Template repo
-  homepage: https://github.com/pq-code-package/tsc
-  default_branch: main
-  has_downloads: false
-  has_issues: true
-  has_projects: true
-  has_wiki: false
-  archived: false
-  private: false
-  allow_squash_merge: true
-  allow_merge_commit: false
-  allow_rebase_merge: true
diff --git a/BUILDING.md b/BUILDING.md
new file mode 100644
index 000000000..2ef94dc67
--- /dev/null
+++ b/BUILDING.md
@@ -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
+```
diff --git a/CODEOWNERS b/CODEOWNERS
index eb74fcb9a..0268df278 100644
--- a/CODEOWNERS
+++ b/CODEOWNERS
@@ -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
diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
deleted file mode 100644
index 9af549938..000000000
--- a/CODE_OF_CONDUCT.md
+++ /dev/null
@@ -1,6 +0,0 @@
-[//]: # (SPDX-License-Identifier: CC-BY-4.0)
-[//]: # (TODO Add code of conduct)
-
-# Code of Conduct
-
-Please see [open issue](https://github.com/pq-code-package/tsc/issues/9)
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 1240c5d16..c1a96d6d1 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -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.
diff --git a/GOVERNANCE.md b/GOVERNANCE.md
deleted file mode 100644
index 9c9dcb3a8..000000000
--- a/GOVERNANCE.md
+++ /dev/null
@@ -1,6 +0,0 @@
-[//]: # (SPDX-License-Identifier: CC-BY-4.0)
-[//]: # (TODO Define governance)
-
-# Governance
-
-to be documented
diff --git a/README.md b/README.md
index c69f7f51c..ac6ab997d 100644
--- a/README.md
+++ b/README.md
@@ -1,115 +1,101 @@
 [//]: # (SPDX-License-Identifier: CC-BY-4.0)
 
-# mlkem-native
-
-**mlkem-native** is a C90 implementation of [ML-KEM](https://doi.org/10.6028/NIST.FIPS.203.ipd) targeting
-PC, mobile and server platforms. It is a fork of the ML-KEM [reference
-implementation](https://github.com/pq-crystals/kyber/tree/main/ref), deviating primarily to (a) accommodate an
-interface for native code (e.g. assembler), and (b) facilitate formal verification. **mlkem-native** provides
-native code backends in C, AArch64 and x86_64, offering state of the art performance on most Arm, Intel and AMD
-platforms.
-
-If you need an ML-KEM implementation suitable for embedded systems, see
-[**mlkem-c-embedded**](https://github.com/pq-code-package/mlkem-c-embedded/).
-
-### Goals
-
-**mlkem-native** aims for _assurance_, _ease of use_, and _performance_. We seek implementations
-which are manually auditable or for which we see a path towards formal verification. All assembly aims
-to be readable and micro-optimization deferred to automated tooling such as
-[SLOTHY](https://slothy-optimizer.github.io/slothy/). Ultimately, **mlkem-native** strives for constant-time
-implementations for which the C-code is verified to be free of undefined behaviour, and where all assembly is
-functionally verified.
-
-### Intended use
+![mlkem_native_logo](docs/images/mlkem_native.png)
 
-**mlkem-native** is currently intended to be used as a code package, where source files of **mlkem-native**
-are imported into a consuming project's source tree and built using that project's build system. The build system
-provided in this repository is for experimental and development purposes only.
-
-### Current state
-
-**mlkem-native** is work in progress. **WE DO NOT CURRENTLY RECOMMEND RELYING ON THIS LIBRARY IN A PRODUCTION
-ENVIRONMENT OR TO PROTECT ANY SENSITIVE DATA.** Once we have the first stable version, this notice will be removed.
+# mlkem-native
 
-#### Performance
+![CI](https://github.com/pq-code-package/mlkem-native/actions/workflows/ci.yml/badge.svg)
+![Benchmarks](https://github.com/pq-code-package/mlkem-native/actions/workflows/bench.yml/badge.svg)
+[![C90](https://img.shields.io/badge/language-C90-blue.svg)](https://web.archive.org/web/20200909074736if_/https://www.pdf-archive.com/2014/10/02/ansi-iso-9899-1990-1/ansi-iso-9899-1990-1.pdf)
+[![Apache](https://img.shields.io/badge/license-Apache--2.0-green.svg)](https://www.apache.org/licenses/LICENSE-2.0)
 
-**mlkem-native** has complete AArch64 and AVX2 backends of competitive performance (see
-[benchmarks](https://pq-code-package.github.io/mlkem-native/dev/bench/)).
+mlkem-native is a C90 implementation of [ML-KEM](https://doi.org/10.6028/NIST.FIPS.203.ipd) targeting
+PC, mobile and server platforms. It is a fork of the ML-KEM [reference
+implementation](https://github.com/pq-crystals/kyber/tree/main/ref).
 
-#### Verification
+mlkem-native aims to be secure, fast, and easy to use: It provides native code backends in C, AArch64 and
+x86_64, offering state of the art performance on most Arm, Intel and AMD platforms (see
+[benchmarks](https://pq-code-package.github.io/mlkem-native/dev/bench/)). The C code in [mlkem/*](mlkem) is verified
+using [CBMC](https://github.com/diffblue/cbmc) to be free of undefined behaviour. In particular, there are no out of
+bounds accesses, nor integer overflows during optimized modular arithmetic.
 
-All C code in [mlkem/*](mlkem) is verified to be memory and type safe using CBMC. This excludes, for example, out of
-bounds accesses, as well as integer overflows during optimized modular arithmetic. See the [CBMC
-Readme](cbmc/proofs/README.md) and the [CBMC Proof Guide](cbmc/proofs/proof_guide.md) for more information and how to
-reproduce the proofs. The code in [fips202/*](fips202) has not yet been verified using CBMC.
+## Quickstart for Ubuntu
 
-Initial experiments are underway to verify AArch64 using [HOL-Light](https://hol-light.github.io/).
+```bash
+# Clone mlkem-native
+git clone https://github.com/pq-code-package/mlkem-native.git
+cd mlkem-native
 
-### Getting started
+# Install base packages
+sudo apt-get update
+sudo apt-get install python3-venv python3-pip make
 
-### Nix setup
+# Setup Python environment
+python3 -m venv venv
+source venv/bin/activate
+python3 -m pip install -r requirements.txt
 
-All the development and build dependencies are specified in [flake.nix](flake.nix). We recommend installing them using
-[nix](https://nixos.org/download/).
+# Build and run base tests
+make quickcheck
 
-To execute a bash shell with the development environment specified in [flake.nix](flake.nix), run
-```bash
-nix develop --experimental-features 'nix-command flakes'
+# Build and run all tests
+./scripts/tests all
 ```
 
-### Native setup
-
-To build **mlkem-native**, you need `make` and a C99 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.:
+See [BUILDING.md](BUILDING.md) for more information.
 
-```bash
-python3 -m venv venv
-./venv/bin/python3 -m pip install -r requirements.txt
-source venv/bin/activate
-```
+## Security
 
-### Using `make`
+mlkem-native is being developed with security at the top of mind. All native code is constant-time in the sense that
+it is free of secret-dependent control flow, memory access, and instructions that are commonly variable-time,
+thwarting most timing side channels.
+The C code is hardened against compiler-introduced timing side channels (such as
+[KyberSlash](https://kyberslash.cr.yp.to/) or [clangover](https://github.com/antoonpurnal/clangover))
+through suitable barriers and constant-time patterns.
 
-You can build tests and benchmarks using the following `make` targets:
+## Formal Verification
 
-```bash
-make mlkem
-make bench
-make bench_components
-make nistkat
-make kat
-```
+We use the [C Bounded Model Checker (CBMC)](https://github.com/diffblue/cbmc) to prove absence of various classes of
+undefined behaviour in C, including out of bounds memory accesses and integer overflows. At present, the proofs cover
+all C code in [mlkem/*](mlkem) involved in running mlkem-native with its C backend. See [cbmc/proofs](cbmc/proofs) for
+details.
 
-The resulting binaries can be found in [test/build](test/build).
+Initial experiments are underway to verify assembly using the [HOL-Light](https://hol-light.github.io/) theorem prover
+and the [s2n-bignum](https://github.com/awslabs/s2n-bignum) infrastructure.
 
-### Windows
+## State
 
-You can also build **mlkem-native** on Windows using `nmake` and an MSVC compiler.
+mlkem-native is in alpha-release stage. We believe it is ready for use, and hope to spark experiments on
+integration into other software before issuing a stable release. If you have any feedback, please reach out! See
+[RELEASE.md](RELEASE.md) for details.
 
-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
-```
+mlkem-native is intended to be used as a code package, where source files are imported into a consuming project's
+source tree and built using that project's build system. The build system provided in this repository is for
+experimental and development purposes only. If you prefer a library-build, please get in touch or open an issue.
 
-### Using `tests` script
+## Design
 
-We recommend compiling and running tests and benchmarks using the [`./scripts/tests`](scripts/tests) script. For
-example,
+mlkem-native is split in a _frontend_ and two _backends_ for arithmetic and FIPS-202 (SHA3). The frontend is
+fixed, written in C and covers all routines that are not critical to performance. The backends are flexible, take care of
+performance-sensitive routines, and can be implemented in C or native code (assembly/intrinsics); see
+[mlkem/native/arith_native.h](mlkem/native/arith_native.h) for the arithmetic backend and
+[fips202/native/fips202_native.h](fips202/native/fips202_native.h) for the FIPS-202 backend. mlkem-native currently
+offers three backends for C, AArch64 and x86_64 - if you'd like contribute new backends, please reach out or just open a
+PR.
 
-```bash
-./scripts/tests func
-```
+Our AArch64 assembly is developed using [SLOTHY](https://github.com/slothy-optimizer/slothy): We write
+'clean' assembly by hand and automate micro-optimizations (e.g. see the [clean](mlkem/native/aarch64/ntt_clean.S)
+vs [optimized](mlkem/native/aarch64/ntt_opt.S) AArch64 NTT).
 
-will compile and run functionality tests. For detailed information on how to use the script, please refer to the
-`--help` option.
+## Have a Question?
 
-### Call for contributors
+If you think you have found a security bug in mlkem-native, please report the vulnerability through
+Github's [private vulnerability reporting](https://github.com/pq-code-package/mlkem-native/security). Please do **not**
+create a public GitHub issue.
 
-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.
+If you have any other question / non-security related issue / feature request, please open a GitHub issue.
 
-### Call for potential consumers
+## Contributing
 
-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.
+If you want to help us build mlkem-native, please reach out. You can contact the mlkem-native team
+through the [PQCA Discord](https://discord.com/invite/xyVnwzfg5R).
diff --git a/RELEASE.md b/RELEASE.md
new file mode 100644
index 000000000..829ce7dc1
--- /dev/null
+++ b/RELEASE.md
@@ -0,0 +1,28 @@
+[//]: # (SPDX-License-Identifier: CC-BY-4.0)
+mlkem-native alpha
+==================
+
+About
+-----
+
+mlkem-native is a C90 implementation of [ML-KEM](https://doi.org/10.6028/NIST.FIPS.203.ipd) targeting
+PC, mobile and server platforms. It is a fork of the ML-KEM [reference
+implementation](https://github.com/pq-crystals/kyber/tree/main/ref).
+
+mlkem-native aims to be fast, secure, and easy to use: It provides native code backends in C, AArch64 and
+x86_64, offering state-of-the-art performance on most Arm, Intel and AMD platforms. The C code in [mlkem/*](mlkem) is
+verified using [CBMC](https://github.com/diffblue/cbmc) to be free of undefined behavior. In particular, there are no
+out of bounds accesses, nor integer overflows during optimized modular arithmetic.
+
+Release notes
+=============
+
+This is first official release of mlkem-native, a C90 implementation of [ML-KEM](https://doi.org/10.6028/NIST.FIPS.203.ipd) targeting
+PC, mobile and server platforms.
+This alpha release of mlkem-native features complete backends in C, AArch64 and x86_64, offering state-of-the-art performance on most Arm, Intel and AMD platforms.
+
+With this alpha release we intend to spark experiments on integrations of mlkem-native in other software.
+We appreciate any feedback on how to improve and extend mlkem-native in the future.
+Please open an issue on https://github.com/pq-code-package/mlkem-native.
+While we continue on improving and extending mlkem-native, we expect that the majority of the code is stable.
+In particular, the core external APIs are stable; we will potentially expose additional functions (e.g., operating on expanded secret keys) in the future.
diff --git a/SECURITY.md b/SECURITY.md
index 26b29e2ec..6b80d9962 100644
--- a/SECURITY.md
+++ b/SECURITY.md
@@ -1,6 +1,8 @@
 [//]: # (SPDX-License-Identifier: CC-BY-4.0)
-[//]: # (TODO Add Security Policy)
 
-# Security
+# Security Policy
 
-Please see [open issue](https://github.com/pq-code-package/tsc/issues/8)
+## Reporting security bugs
+
+If you think you have found a security bug in mlkem-native, please report the vulnerability through
+Github's [private vulnerability reporting](https://github.com/pq-code-package/mlkem-native/security).
diff --git a/SUPPORT.md b/SUPPORT.md
deleted file mode 100644
index ead4aa114..000000000
--- a/SUPPORT.md
+++ /dev/null
@@ -1,6 +0,0 @@
-[//]: # (SPDX-License-Identifier: CC-BY-4.0)
-[//]: # (TODO add support information)
-
-# Support
-
-To be written.
diff --git a/docs/images/mlkem_native.png b/docs/images/mlkem_native.png
new file mode 100644
index 0000000000000000000000000000000000000000..bc5faa4e62bb9259efd8cb2e528a95e8c9f14fb0
GIT binary patch
literal 13534
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

literal 0
HcmV?d00001

diff --git a/scripts/ci/lint b/scripts/ci/lint
index fa7a86290..3c33aeb13 100755
--- a/scripts/ci/lint
+++ b/scripts/ci/lint
@@ -63,7 +63,7 @@ echo "::endgroup::"
 
 check-eol-dry-run()
 {
-  for file in $(git ls-files -- ":/"); do
+  for file in $(git ls-files -- ":/" ":/!:*.png"); do
     if [[ $(tail -c1 "$file" | wc -l) == 0 ]]; then
       l=$(wc -l <"$file")
       echo "$file $l"
@@ -77,7 +77,7 @@ echo "::endgroup::"
 check-spdx()
 {
   local success=true
-  for file in $(git ls-files -- ":/" ":/!:*.json" ":/!:*LICENSE*" ":/!:.git*" ":/!:flake.lock"); do
+  for file in $(git ls-files -- ":/" ":/!:*.json" ":/!:*.png" ":/!:*LICENSE*" ":/!:.git*" ":/!:flake.lock"); do
     if [[ $(grep "SPDX-License-Identifier:" $file | wc -l) == 0 ]]; then
       echo "::error file=$file,line=${line:-1},title=Missing license header error::$file is missing SPDX License header"
       success=false
diff --git a/scripts/format b/scripts/format
index 5a0757679..267811204 100755
--- a/scripts/format
+++ b/scripts/format
@@ -34,7 +34,7 @@ clang-format -i $(git ls-files ":/*.c" ":/*.h")
 info "Checking for eol"
 check-eol()
 {
-  for file in $(git ls-files -- ":/"); do
+  for file in $(git ls-files -- ":/" ":/!:*.png"); do
     if [[ $(tail -c1 "$file" | wc -l) == 0 ]]; then
       echo "" >>"$file"
       echo "$file"