From 94aaa32a897e9e0fe695117b30a3ba8809669bc1 Mon Sep 17 00:00:00 2001 From: Phil Milewski Date: Sun, 23 Nov 2025 14:48:30 +0100 Subject: [PATCH 1/4] first draft contribution --- CONTRIBUTING.md | 169 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 169 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..1eb4d6ac --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,169 @@ +# Contributing + +This library has been designed for prototyping lattice-based cryptography. Do you miss a common function for your own prototype or did you design your own scheme and want it added to this library? You are welcome to add it and we are happy help you. + +More generally, all contributions such as bugfixes, documentation and tests are welcome. Please go ahead and submit your pull requests. + +## Choosing the right location + +The qfall library is divided into thre different repositories: [qFALL-math](https://github.com/qfall/math), [qFALL-tools](https://github.com/qfall/tools) and [qFALL-schemes](https://github.com/qfall/schemes). + +To decide where ro add your code, ask the following questions: + + - Is your code a general mathematical function, e.g. addition or LLL? -> add your code to [qFALL-math](https://github.com/qfall/math). + - Is your code a construction that is commonly used in the construction of lattice based schemes, e.g. g-trapdoors? -> add your code to [qFALL-tools](https://github.com/qfall/tools). + - Is your code one specific scheme or prototype, e.g. 'scheme XY of paper Z'? -> add your code to [qFALL-schemes](https://github.com/qfall/schemes). + +When in doubt, just submit your pull request to the repository you feel is best suited for your code. + +## Style Guide + + +## Pull request template + +Every pull request will use this template by default: + +> **Description** +> +> +> +> This PR implements... +> - [ ] feature/ revision/ hotfix/ optimisation/ ... +> +> for/ of `Component`. +> +> +> +> **Testing** +> +> +> +> +> - [ ] I added basic working examples (possibly in doc-comment) +> - [ ] I added tests for large (pointer representation) values +> - [ ] I triggered all possible errors in my test in every possible way +> - [ ] I included tests for all reasonable edge cases +> +> +> **Checklist:** +> +> +> +> - [ ] I have performed a self-review of my own code +> - [ ] The code provides good readability and maintainability s.t. it fulfills best practices like talking code, modularity, ... +> - [ ] The chosen implementation is not more complex than it has to be +> - [ ] My code should work as intended and no side effects occur (e.g. memory leaks) +> - [ ] The doc comments fit our style guide +> - [ ] I have credited related sources if needed + + +## Disclaimer + +Currently, we are in the development phase and interfaces might change. +Feel free to check out the current progress, but be aware, that the content will +change in the upcoming weeks and months. An official release will most likely be published in the second half of 2024. + +## Quick-Start + +Please refer to [our website](https://qfall.github.io/) as a central information point. + +To install and add our library to your project, please refer to [our tutorial](https://qfall.github.io/book/index.html). +It provides a step-by-step guide to install the required libraries and gives further insights into the usage of our crates. + +## What does qFALL-math offer? + +Extensive documentation can be generated using + +```bash +cargo doc # suffix with --open to directly open the documentation +``` + +once the project is cloned. Following, there is a small overview containing the general types of our library [qFALL-math](https://github.com/qfall/math). + +```bash +math +├── ... +├── src +│ ├── integer # src folder containing implementations of integers +│ ├── integer_mod_q # src folder containing implementations of integers +│ │ # for which a certain modulus is applied +│ └── rational # src folder containing implementations of rationals +└── ... +``` + +### Integers + +- [`Z`](https://github.com/qfall/math/blob/dev/src/integer/z.rs): Represents $\mathbb Z$. +- [`MatZ`](https://github.com/qfall/math/blob/dev/src/integer/mat_z.rs): Represents matrices of $\mathbb Z$. +- [`PolyOverZ`](https://github.com/qfall/math/blob/dev/src/integer/poly_over_z.rs): Represents polynomials with coefficients over $\mathbb Z$. +- [`MatPolyOverZ`](https://github.com/qfall/math/blob/dev/src/integer/mat_poly_over_z.rs): Represents matrices of polynomials with coefficients over $\mathbb Z$. + +```rust +use qfall_math::integer::Z; + +let a = Z::from(24); +let b = Z::from(42); + +let res_add: Z = &a + &b; +let res_sub: Z = a - 10; +let res_mul: Z = 3 * b; +``` + +### Integers mod q + +- [`Zq`](https://github.com/qfall/math/blob/dev/src/integer_mod_q/zq.rs): Represents $\mathbb Z_q$. +- [`MatZq`](https://github.com/qfall/math/blob/dev/src/integer_mod_q/mat_zq.rs): Represents matrices of $\mathbb Z_q$. +- [`PolyOverZq`](https://github.com/qfall/math/blob/dev/src/integer_mod_q/poly_over_zq.rs): Represents polynomials with coefficients over $\mathbb Z_q$. +- [`PolynomialRingZq`](https://github.com/qfall/math/blob/dev/src/integer_mod_q/polynomial_ring_zq.rs): Represents quotient rings of $\mathbb Z_q[X]/f(X)$ where $q$ is an integer modulus and $f(X)$ is a [`PolyOverZq`](https://github.com/qfall/math/blob/dev/src/integer_mod_q/poly_over_zq.rs). +- [`MatPolynomialRingZq`](https://github.com/qfall/math/blob/dev/src/integer_mod_q/mat_polynomial_ring_zq.rs): Represents matrices of quotient rings of $\mathbb Z_q[X]/f(X)$ where $q$ is an integer modulus and $f(X)$ is a [`PolyOverZq`](https://github.com/qfall/math/blob/dev/src/integer_mod_q/poly_over_zq.rs). + +```rust +use qfall_math::integer_mod_q::Zq; +use qfall_math::integer_mod_q::Modulus; + +let modulus = Modulus::from(24); +let a = Zq::from((42, &modulus)); +let b = Zq::from((17, &modulus)); + +let res_add: Zq = &a + &b; +let res_sub: Zq = a - 10; +let res_mul: Zq = 3 * b; +``` + +### Rationals + +- [`Q`](https://github.com/qfall/math/blob/dev/src/rational/q.rs): Represents $\mathbb Q$. +- [`MatQ`](https://github.com/qfall/math/blob/dev/src/rational/mat.rs): Represents matrices of $\mathbb Q$. +- [`PolyOverQ`](https://github.com/qfall/math/blob/dev/src/rational/poly_over_q.rs): Represents polynomials with coefficients over $\mathbb Q$. + +```rust +use qfall_math::rational::Q; + +let a = Q::from((17, 19)); +let b = Q::from(0.5); + +let res_add: Q = &a + &b; +let res_sub: Q = a - 10.5; +let res_mul: Q = 3 * b; +``` + +## External Libraries + +This project uses the C-based, optimized math library [FLINT](https://flintlib.org/). To use a C-library in Rust, there has to be an FFI (Foreign Function Interface) which allows to call the methods from [FLINT](https://flintlib.org/) in Rust. This project uses the crate [flint-sys](https://github.com/alex-ozdemir/flint-rs/tree/master/flint-sys) as a binding for [FLINT](https://flintlib.org/). +Furthermore, we utilized [serde](https://crates.io/crates/serde) and [serde_json](https://crates.io/crates/serde_json) to (de-)serialize objects to and from JSON. Last, but not least, our sampling algorithms heavily rely on the [rand-crate](https://crates.io/crates/rand). An extensive list can be found in our `Cargo.toml` file. + +## License + +This library is distributed under the **Mozilla Public License Version 2.0** which can be found here [License](https://github.com/qfall/math/blob/dev/LICENSE). +Permissions of this weak copyleft license are conditioned on making available the source code of licensed files and modifications of those files under the same license (or in certain cases, one of the GNU licenses). Copyright and license notices must be preserved. Contributors provide an express grant of patent rights. However, a larger work using the licensed work may be distributed under different terms and without source code for files added to the larger work. + + +## Get in Touch + +To contact us, please refer to our mailing list `pg-qfall(at)lists.upb.de`. From 2f737e4c7790f580fb77dcbb75b7b2df9ca1029c Mon Sep 17 00:00:00 2001 From: Phil Milewski Date: Sun, 23 Nov 2025 16:57:41 +0100 Subject: [PATCH 2/4] finish contributing --- CONTRIBUTING.md | 156 ++++++++++++++++++------------------------------ 1 file changed, 58 insertions(+), 98 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1eb4d6ac..343fb2c1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -17,7 +17,61 @@ To decide where ro add your code, ask the following questions: When in doubt, just submit your pull request to the repository you feel is best suited for your code. ## Style Guide +Our Style guide is based on the [rust standard](https://github.com/rust-lang/rfcs/blob/master/text/0505-api-comment-conventions.md). +Every function should have a documentation. A documentation includes a description of the function, a description of every parameter, the output behavior and an example. If applicable it also includes, Error and Panic behavior and references to scientific literature. + +Here is an example documentation: + +```rust +impl Z { + /// Chooses a [`Z`] instance according to the discrete Gaussian distribution + /// in `[center - ⌈6 * s⌉ , center + ⌊6 * s⌋ ]`. + /// + /// This function samples discrete Gaussians according to the definition of + /// SampleZ in [GPV08](https://citeseerx.ist.psu.edu/document?repid=rep1&type=pdf&doi=d9f54077d568784c786f7b1d030b00493eb3ae35). + /// + /// Parameters: + /// - `n`: specifies the range from which is sampled + /// - `center`: specifies the position of the center with peak probability + /// - `s`: specifies the Gaussian parameter, which is proportional + /// to the standard deviation `sigma * sqrt(2 * pi) = s` + /// + /// Returns new [`Z`] sample chosen according to the specified discrete Gaussian + /// distribution or a [`MathError`] if the specified parameters were not chosen + /// appropriately, i.e. `s < 0`. + /// + /// # Examples + /// ``` + /// use qfall_math::integer::Z; + /// + /// let sample = Z::sample_discrete_gauss(0, 1).unwrap(); + /// ``` + /// + /// # Errors and Failures + /// - Returns a [`MathError`] of type [`InvalidIntegerInput`](MathError::InvalidIntegerInput) + /// if `s < 0`. + /// + /// This function implements SampleZ according to: + /// - \[1\] Gentry, Craig and Peikert, Chris and Vaikuntanathan, Vinod (2008). + /// Trapdoors for hard lattices and new cryptographic constructions. + /// In: Proceedings of the fortieth annual ACM symposium on Theory of computing. + /// + pub fn sample_discrete_gauss(center: impl Into, s: impl Into) -> Result { + let center: Q = center.into(); + let s: Q = s.into(); + + let mut dgis = DiscreteGaussianIntegerSampler::init( + ¢er, + &s, + unsafe { TAILCUT }, + LookupTableSetting::NoLookup, + )?; + + Ok(dgis.sample_z()) + } +} +``` ## Pull request template @@ -63,107 +117,13 @@ Every pull request will use this template by default: > - [ ] I have credited related sources if needed -## Disclaimer - -Currently, we are in the development phase and interfaces might change. -Feel free to check out the current progress, but be aware, that the content will -change in the upcoming weeks and months. An official release will most likely be published in the second half of 2024. - -## Quick-Start - -Please refer to [our website](https://qfall.github.io/) as a central information point. - -To install and add our library to your project, please refer to [our tutorial](https://qfall.github.io/book/index.html). -It provides a step-by-step guide to install the required libraries and gives further insights into the usage of our crates. - -## What does qFALL-math offer? - -Extensive documentation can be generated using +### Formating +All code has to comply with *clippy* format. +This can be ensured by running ```bash -cargo doc # suffix with --open to directly open the documentation -``` - -once the project is cloned. Following, there is a small overview containing the general types of our library [qFALL-math](https://github.com/qfall/math). - -```bash -math -├── ... -├── src -│ ├── integer # src folder containing implementations of integers -│ ├── integer_mod_q # src folder containing implementations of integers -│ │ # for which a certain modulus is applied -│ └── rational # src folder containing implementations of rationals -└── ... -``` - -### Integers - -- [`Z`](https://github.com/qfall/math/blob/dev/src/integer/z.rs): Represents $\mathbb Z$. -- [`MatZ`](https://github.com/qfall/math/blob/dev/src/integer/mat_z.rs): Represents matrices of $\mathbb Z$. -- [`PolyOverZ`](https://github.com/qfall/math/blob/dev/src/integer/poly_over_z.rs): Represents polynomials with coefficients over $\mathbb Z$. -- [`MatPolyOverZ`](https://github.com/qfall/math/blob/dev/src/integer/mat_poly_over_z.rs): Represents matrices of polynomials with coefficients over $\mathbb Z$. - -```rust -use qfall_math::integer::Z; - -let a = Z::from(24); -let b = Z::from(42); - -let res_add: Z = &a + &b; -let res_sub: Z = a - 10; -let res_mul: Z = 3 * b; +cargo clippy ``` - -### Integers mod q - -- [`Zq`](https://github.com/qfall/math/blob/dev/src/integer_mod_q/zq.rs): Represents $\mathbb Z_q$. -- [`MatZq`](https://github.com/qfall/math/blob/dev/src/integer_mod_q/mat_zq.rs): Represents matrices of $\mathbb Z_q$. -- [`PolyOverZq`](https://github.com/qfall/math/blob/dev/src/integer_mod_q/poly_over_zq.rs): Represents polynomials with coefficients over $\mathbb Z_q$. -- [`PolynomialRingZq`](https://github.com/qfall/math/blob/dev/src/integer_mod_q/polynomial_ring_zq.rs): Represents quotient rings of $\mathbb Z_q[X]/f(X)$ where $q$ is an integer modulus and $f(X)$ is a [`PolyOverZq`](https://github.com/qfall/math/blob/dev/src/integer_mod_q/poly_over_zq.rs). -- [`MatPolynomialRingZq`](https://github.com/qfall/math/blob/dev/src/integer_mod_q/mat_polynomial_ring_zq.rs): Represents matrices of quotient rings of $\mathbb Z_q[X]/f(X)$ where $q$ is an integer modulus and $f(X)$ is a [`PolyOverZq`](https://github.com/qfall/math/blob/dev/src/integer_mod_q/poly_over_zq.rs). - -```rust -use qfall_math::integer_mod_q::Zq; -use qfall_math::integer_mod_q::Modulus; - -let modulus = Modulus::from(24); -let a = Zq::from((42, &modulus)); -let b = Zq::from((17, &modulus)); - -let res_add: Zq = &a + &b; -let res_sub: Zq = a - 10; -let res_mul: Zq = 3 * b; -``` - -### Rationals - -- [`Q`](https://github.com/qfall/math/blob/dev/src/rational/q.rs): Represents $\mathbb Q$. -- [`MatQ`](https://github.com/qfall/math/blob/dev/src/rational/mat.rs): Represents matrices of $\mathbb Q$. -- [`PolyOverQ`](https://github.com/qfall/math/blob/dev/src/rational/poly_over_q.rs): Represents polynomials with coefficients over $\mathbb Q$. - -```rust -use qfall_math::rational::Q; - -let a = Q::from((17, 19)); -let b = Q::from(0.5); - -let res_add: Q = &a + &b; -let res_sub: Q = a - 10.5; -let res_mul: Q = 3 * b; -``` - -## External Libraries - -This project uses the C-based, optimized math library [FLINT](https://flintlib.org/). To use a C-library in Rust, there has to be an FFI (Foreign Function Interface) which allows to call the methods from [FLINT](https://flintlib.org/) in Rust. This project uses the crate [flint-sys](https://github.com/alex-ozdemir/flint-rs/tree/master/flint-sys) as a binding for [FLINT](https://flintlib.org/). -Furthermore, we utilized [serde](https://crates.io/crates/serde) and [serde_json](https://crates.io/crates/serde_json) to (de-)serialize objects to and from JSON. Last, but not least, our sampling algorithms heavily rely on the [rand-crate](https://crates.io/crates/rand). An extensive list can be found in our `Cargo.toml` file. - -## License - -This library is distributed under the **Mozilla Public License Version 2.0** which can be found here [License](https://github.com/qfall/math/blob/dev/LICENSE). -Permissions of this weak copyleft license are conditioned on making available the source code of licensed files and modifications of those files under the same license (or in certain cases, one of the GNU licenses). Copyright and license notices must be preserved. Contributors provide an express grant of patent rights. However, a larger work using the licensed work may be distributed under different terms and without source code for files added to the larger work. - - ## Get in Touch To contact us, please refer to our mailing list `pg-qfall(at)lists.upb.de`. From e54b224fa2752eef17bd7d7503705aa46ad3ddae Mon Sep 17 00:00:00 2001 From: jnsiemer Date: Thu, 27 Nov 2025 18:04:03 +0000 Subject: [PATCH 3/4] Revise contributing --- CONTRIBUTING.md | 114 ++++++++++++------------------------------------ 1 file changed, 27 insertions(+), 87 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 343fb2c1..51eb750b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,28 +1,35 @@ # Contributing - -This library has been designed for prototyping lattice-based cryptography. Do you miss a common function for your own prototype or did you design your own scheme and want it added to this library? You are welcome to add it and we are happy help you. +This library is designed to prototype lattice-based cryptography. Our intent for this library is to be maintained by the community. We encourage anyone to add missing, frequently used features for lattice-based prototyping to this library and we are happy help with that process. More generally, all contributions such as bugfixes, documentation and tests are welcome. Please go ahead and submit your pull requests. ## Choosing the right location +The qFALL library is divided into three repositories: [qFALL-math](https://github.com/qfall/math), [qFALL-tools](https://github.com/qfall/tools) and [qFALL-schemes](https://github.com/qfall/schemes). + +Please add new features to one of these repositories roughly following these guidelines. +- If your feature implements a general mathematical function, then add your code to [qFALL-math](https://github.com/qfall/math). +- If your feature implements a fundamental primitive or shortcut that is commonly used in the construction of lattice based schemes, e.g. G-trapdoors, then add your code to [qFALL-tools](https://github.com/qfall/tools). +- If you implement a construction, e.g. Kyber, then add your code to [qFALL-schemes](https://github.com/qfall/schemes). + +When in doubt, just submit your pull request to the repository you feel is best suited for your code. We will sort it. + +## Style Guide +Our style guide is based on the [rust standard](https://github.com/rust-lang/rfcs/blob/master/text/0505-api-comment-conventions.md). These rules summarise our style guidelines. +- Every function should be documented. A doc-comment includes a concise description of the function and an example. In case, it receives parameters other than `self`, it also includes a description of every parameter and the output type and behavior. If applicable it also includes, Error and Panic behavior and references to scientific literature. +- If the code of your function is not self-explanatory from your doc-comment, use inline-comments `//` to briefly describe the steps. +- A file should always have the copyright notice at the top, followed by a very brief inner doc-comment to summarise the purpose of this file, grouped up imports, implementations of all features, and finally tests of each feature in a separate test-module with a brief doc-comment for each test. +- Overall, any feature should get a descriptive but concise name s.t. it can be discovered intuitively. +- Code in our library needs to be formatted using `cargo fmt` and satisfy `clippy`'s standards. +- We aim for multiple tests per function, its unforseen behavior, panic or error-cases to boost confidence in our implementations and ensure that modifications of a function only introduce intended changes of behavior. +- Last but not least, we would like to minimise the number of dependencies of all crates to keep them as slim and quickly compilable as possible. + +## Documentation +The documentation for each crate is available online and it can be generated locally by running the following command in the root directory of this repository. +```bash +cargo doc --open +``` -The qfall library is divided into thre different repositories: [qFALL-math](https://github.com/qfall/math), [qFALL-tools](https://github.com/qfall/tools) and [qFALL-schemes](https://github.com/qfall/schemes). - -To decide where ro add your code, ask the following questions: - - - Is your code a general mathematical function, e.g. addition or LLL? -> add your code to [qFALL-math](https://github.com/qfall/math). - - Is your code a construction that is commonly used in the construction of lattice based schemes, e.g. g-trapdoors? -> add your code to [qFALL-tools](https://github.com/qfall/tools). - - Is your code one specific scheme or prototype, e.g. 'scheme XY of paper Z'? -> add your code to [qFALL-schemes](https://github.com/qfall/schemes). - -When in doubt, just submit your pull request to the repository you feel is best suited for your code. - -## Style Guide -Our Style guide is based on the [rust standard](https://github.com/rust-lang/rfcs/blob/master/text/0505-api-comment-conventions.md). - -Every function should have a documentation. A documentation includes a description of the function, a description of every parameter, the output behavior and an example. If applicable it also includes, Error and Panic behavior and references to scientific literature. - -Here is an example documentation: - +Furthermore, here is an example for a doc-comment of a function that follows our guidelines. ```rust impl Z { /// Chooses a [`Z`] instance according to the discrete Gaussian distribution @@ -57,73 +64,6 @@ impl Z { /// Trapdoors for hard lattices and new cryptographic constructions. /// In: Proceedings of the fortieth annual ACM symposium on Theory of computing. /// - pub fn sample_discrete_gauss(center: impl Into, s: impl Into) -> Result { - let center: Q = center.into(); - let s: Q = s.into(); - - let mut dgis = DiscreteGaussianIntegerSampler::init( - ¢er, - &s, - unsafe { TAILCUT }, - LookupTableSetting::NoLookup, - )?; - - Ok(dgis.sample_z()) - } + pub fn sample_discrete_gauss(center: impl Into, s: impl Into) -> Result {...} } ``` - -## Pull request template - -Every pull request will use this template by default: - -> **Description** -> -> -> -> This PR implements... -> - [ ] feature/ revision/ hotfix/ optimisation/ ... -> -> for/ of `Component`. -> -> -> -> **Testing** -> -> -> -> -> - [ ] I added basic working examples (possibly in doc-comment) -> - [ ] I added tests for large (pointer representation) values -> - [ ] I triggered all possible errors in my test in every possible way -> - [ ] I included tests for all reasonable edge cases -> -> -> **Checklist:** -> -> -> -> - [ ] I have performed a self-review of my own code -> - [ ] The code provides good readability and maintainability s.t. it fulfills best practices like talking code, modularity, ... -> - [ ] The chosen implementation is not more complex than it has to be -> - [ ] My code should work as intended and no side effects occur (e.g. memory leaks) -> - [ ] The doc comments fit our style guide -> - [ ] I have credited related sources if needed - - -### Formating - -All code has to comply with *clippy* format. -This can be ensured by running -```bash -cargo clippy -``` -## Get in Touch - -To contact us, please refer to our mailing list `pg-qfall(at)lists.upb.de`. From a221464c3b5803edf1d00f8adcee8040ca7d5acf Mon Sep 17 00:00:00 2001 From: Jan Niklas Siemer Date: Fri, 28 Nov 2025 16:11:03 +0000 Subject: [PATCH 4/4] Apply suggestions from code review Co-authored-by: Marvin Beckmann --- CONTRIBUTING.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 51eb750b..80a0c3a2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,26 +1,26 @@ # Contributing -This library is designed to prototype lattice-based cryptography. Our intent for this library is to be maintained by the community. We encourage anyone to add missing, frequently used features for lattice-based prototyping to this library and we are happy help with that process. +This library is designed to prototype lattice-based cryptography. Our intent for this library is to be maintained by the community. We encourage anyone to add missing, frequently used features for lattice-based prototyping to this library, and we are happy to help with that process. More generally, all contributions such as bugfixes, documentation and tests are welcome. Please go ahead and submit your pull requests. ## Choosing the right location The qFALL library is divided into three repositories: [qFALL-math](https://github.com/qfall/math), [qFALL-tools](https://github.com/qfall/tools) and [qFALL-schemes](https://github.com/qfall/schemes). -Please add new features to one of these repositories roughly following these guidelines. +Please add new features to one of these repositories, roughly following these guidelines. - If your feature implements a general mathematical function, then add your code to [qFALL-math](https://github.com/qfall/math). -- If your feature implements a fundamental primitive or shortcut that is commonly used in the construction of lattice based schemes, e.g. G-trapdoors, then add your code to [qFALL-tools](https://github.com/qfall/tools). -- If you implement a construction, e.g. Kyber, then add your code to [qFALL-schemes](https://github.com/qfall/schemes). +- If your feature implements a fundamental primitive or shortcut that is commonly used in the construction of lattice-based schemes, e.g., G-trapdoors, then add your code to [qFALL-tools](https://github.com/qfall/tools). +- If you implement a construction, e.g., Kyber, then add your code to [qFALL-schemes](https://github.com/qfall/schemes). When in doubt, just submit your pull request to the repository you feel is best suited for your code. We will sort it. ## Style Guide Our style guide is based on the [rust standard](https://github.com/rust-lang/rfcs/blob/master/text/0505-api-comment-conventions.md). These rules summarise our style guidelines. -- Every function should be documented. A doc-comment includes a concise description of the function and an example. In case, it receives parameters other than `self`, it also includes a description of every parameter and the output type and behavior. If applicable it also includes, Error and Panic behavior and references to scientific literature. +- Every function should be documented. A doc-comment includes a concise description of the function and an example. In case it receives parameters other than `self`, it also includes a description of every parameter, the output type, and behavior. If applicable, it also includes Error and Panic behavior and references to scientific literature. - If the code of your function is not self-explanatory from your doc-comment, use inline-comments `//` to briefly describe the steps. - A file should always have the copyright notice at the top, followed by a very brief inner doc-comment to summarise the purpose of this file, grouped up imports, implementations of all features, and finally tests of each feature in a separate test-module with a brief doc-comment for each test. - Overall, any feature should get a descriptive but concise name s.t. it can be discovered intuitively. - Code in our library needs to be formatted using `cargo fmt` and satisfy `clippy`'s standards. -- We aim for multiple tests per function, its unforseen behavior, panic or error-cases to boost confidence in our implementations and ensure that modifications of a function only introduce intended changes of behavior. +- We aim for multiple tests per function, its unforeseen behavior, panic or error-cases to boost confidence in our implementations and ensure that modifications of a function only introduce intended changes of behavior. - Last but not least, we would like to minimise the number of dependencies of all crates to keep them as slim and quickly compilable as possible. ## Documentation @@ -29,7 +29,7 @@ The documentation for each crate is available online and it can be generated loc cargo doc --open ``` -Furthermore, here is an example for a doc-comment of a function that follows our guidelines. +Furthermore, here is an example of a doc-comment of a function that follows our guidelines. ```rust impl Z { /// Chooses a [`Z`] instance according to the discrete Gaussian distribution