Skip to content

Commit

Permalink
adding contributing guideline (#259)
Browse files Browse the repository at this point in the history
* adding contributing guideline 

* adding further dev support information
  • Loading branch information
baentsch authored Sep 22, 2023
1 parent 5d8952b commit f332584
Show file tree
Hide file tree
Showing 2 changed files with 136 additions and 0 deletions.
78 changes: 78 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -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).



58 changes: 58 additions & 0 deletions DEVELOPMENT.md
Original file line number Diff line number Diff line change
@@ -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).


0 comments on commit f332584

Please sign in to comment.