The OQS core team welcomes all proposals to improve this project. This may take the form of a discussion for input or feedback, possible bug reports or feature requests via issues as well as new code and documentation via a pull request (PR).
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 particularly in case of possible bugs or new feature requests or create a discussion.
Pull requests should clearly state their purpose, possibly referencing an existing issue 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.
This project has adopted a slightly modified Google code formatting style for the core components
of the library as documented in the style template.
The astyle tool is used to check formatting in CI.
Due to variations in behaviour across version and platforms, it is possible to encounter CI failures even if code has been locally formatted with astyle.
To assist with this inconvenience, we provide a convenience script which runs astyle in the same Docker image that we use for the CI checks:
LIBOQS_DIR=<liboqs directory> ./scripts/format_code.shThis script has been tested on x86_64 Ubuntu and arm64 macOS. Contributions for other platforms are welcome and appreciated!
liboqs uses GitHub Actions for CI.
For a comprehensive overview of our CI setup, see CI.md.
OQS attempts to be responsible with resource usage and only runs a minimal set of tests automatically on push. A more thorough test suite runs automatically on pull requests. To trigger these tests before creating a PR, include the string "[full tests]" in a commit message. Other trigger strings are documented in CI.md.
Act is a tool facilitating local execution of
GitHub CI jobs. When executed in the main liboqs 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 .
Modifications to GitHub Actions workflows are checked with actionlint during the basic.yml job, protecting the CI chain and against wrong approval decisions based on improper CI runs. Changes to these workflows can be validated locally with actionlint:
actionlint .github/workflows/*.ymlor running the CI locally (as above):
act workflow_call -W '.github/workflows/basic.yml'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.
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.
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".