diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..bcd1793f --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,78 @@ +# Contributing + +The OQS core team welcomes all proposals to improve this project. This may take +the form of [a discussion](https://github.com/open-quantum-safe/oqs-provider/discussions) +for input or feedback, possible bug reports or feature requests via [issues](https://github.com/open-quantum-safe/oqs-provider/issues) +as well as new code and documentation via a [pull request (PR)](https://github.com/open-quantum-safe/oqs-provider/pulls). + +## Review and Feedback + +We aim to provide timely feedback to any input. If you are uncertain as to whether +a particular contribution is welcome, needed or timely, please first open an [issue](https://github.com/open-quantum-safe/oqs-provider/issues) +particularly in case of possible bugs or new feature requests or create a +[discussion](https://github.com/open-quantum-safe/oqs-provider/discussions). + +## Pull requests + +Pull requests should clearly state their purpose, possibly referencing an existing +[issue](https://github.com/open-quantum-safe/oqs-provider/issues) when resolving it. + +All PRs should move to "Ready for Review" stage only if all CI tests pass (are green). + +The OQS core team is happy to provide feedback also to Draft PRs in order to improve +them before the final "Review" stage. + +### Coding style + +This project has adopted the [OpenSSL coding style](https://www.openssl.org/policies/technical/coding-style.html). +To check adherence of any new code to this, it therefore is highly recommended to +run the following command in the project main directory prior to finishing a PR: + + find oqsprov -type f -and '(' -name '*.h' -or -name '*.c' -or -name '*.inc' ')' | xargs clang-format --dry-run --Werror + +### Running CI locally + +#### CircleCI + +If encountering CI errors in CircleCI, it may be helpful to execute the test jobs +locally to debug. This can be facilitated by executing the command + + circleci local execute --job some-test-job + +assuming "some-test-job" is the name of the test to be executed and the CircleCI +[command line tools have been installed](https://circleci.com/docs/local-cli). + +#### Github CI + +[Act](https://github.com/nektos/act) is a tool facilitating local execution of +github CI jobs. When executed in the main `oqsprovider` directory, + + act -l Displays all github CI jobs + act -j some-job Executes "some-job" + +When installing `act` as a github extension, prefix the commands with `gh `. + +### New features + +Any PR introducing a new feature is expected to contain a test of this feature +and this test should be part of the CI pipeline, preferably using Github CI. + +## Background knowledge + +New contributors are recommended to first check out documentation of the +[OpenSSL provider concept](https://www.openssl.org/docs/man3.0/man7/provider.html) +as well as the baseline API of [liboqs](https://github.com/open-quantum-safe/liboqs) +which are the two core foundations for this project. + +## Failsafe + +If you feel your contribution is not getting proper attention, please be sure to +add a tag to one or more of our [most active contributors](https://github.com/open-quantum-safe/oqs-provider/graphs/contributors). + +## Issues to start working on + +If you feel like contributing but don't know what specific topic to work on, +please check the [open issues tagged "good first issue" or "help wanted"](https://github.com/open-quantum-safe/oqs-provider/issues). + + + diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md new file mode 100644 index 00000000..8be3fb56 --- /dev/null +++ b/DEVELOPMENT.md @@ -0,0 +1,58 @@ +# Development guidelines + +## Basics + +Every developer has their own coding style and diversity in general is good and welcome. + +We nevertheless do try to follow some basic goals in this project: + +- All pieces should be readable / understandable without having to comprehend all parts first. +- Therefore, comments (incl. cross references where sensible) are encouraged. +- For syntactical legibility the project adopted the [OpenSSL coding convention](https://www.openssl.org/policies/technical/coding-style.html) +- Tooling exists to validate the coding convention: Simply execute `clang-format --dry-run --Werror file-to-test` +- Platform-specific code should be avoided to the greatest extent possible as the project aims to run correctly at least on Linux, MacOS and Windows (x64 and aarch64 architectures). + +## Generated code + +Significant parts of the code are generated via the script `oqs-template/generate.py`. +This script serves to import a specific version of [liboqs](https://github.com/open-quantum-safe/liboqs) +into `oqsprovider`. Most notably the control file `oqs-template/generate.yml` has to be +in sync with the specific `liboqs` version: algorithm IDs, e.g., signature algorithm +OIDs need to be aligned with the specific algorithm code version. +Therefore, no code within the generator brackets must be changed: + +``` +///// OQS_TEMPLATE_FRAGMENT_..._START +... +///// OQS_TEMPLATE_FRAGMENT_..._END +``` + +If such code changes are required they have to be implemented in the generator code +fragments located in the `oqs-template` directory. + +During normal code development it is very unlikely any of these files need to be touched. + +## Plain build + +If the prerequisites for `oqsprovider` are met on a development machine, i.e. +presence of `liboqs` and `openssl` (v.3) the build can simply be executed by +running `scripts/fullbuild.sh`. Various parameters exist and are documented +in the script to adapt to a specific build environment and in [the documentation](CONFIGURE.md#convenience-build-script-options). +The script can also be used to build a specific `openssl` and a specific `liboqs` +version as well as debug versions of all components. + +## Plain test + +All tests meant for local feature testing are integrated/made available for +execution in the script `scripts/runtest.sh`. PRs should only be considered +if all tests pass locally as the CI system uses them too. + +## Debugging + +Project-specific debugging facilities are documented in [the wiki](https://github.com/open-quantum-safe/oqs-provider/wiki/Debugging). + +For "classic" `gdb` style debugging, be certain to set "-DCMAKE_BUILD_TYPE=Debug" +when building `oqsprovider` and `-d` when configuring `openssl` (see +"scripts/fullbuild.sh" for further information where best to do this). + +