Welcome! You are reading about how to contribute code to VOLK. First of all, we are very happy that you're about to contribute, and welcome your submissions! We hope many more will come.
In this document, we will explain the main things to consider when submitting pull requests against VOLK. Reading this first will help a lot with streamlining the process of getting your code merged.
There is also a wiki-based version of this file, which contains more detail. VOLK is part of the GNU Radio project and as such, it follows the same contribution guidelines. This file is an adopted GNU Radio checklist.
Those are at least as important as code contributions: Emails to the mailing list, answers on Stack Overflow, Wiki page edits, examples... We very much appreciate those. However, this document is specifically about contributing code.
Any code contributions going into VOLK will become part of an LGPL-licensed (former contributions are GPL-licensed), open source repository. It is therefore imperative that code submissions belong to the authors, and that submitters have the authority to merge that code into the public VOLK codebase.
For that purpose, we use the Developer's Certificate of Origin. It is the same document used by other projects. Signing the DCO states that there are no legal reasons to not merge your code.
To sign the DCO, suffix your git commits with a "Signed-off-by" line. When
using the command line, you can use git commit -s to automatically add this
line. If there were multiple authors of the code, or other types of
stakeholders, make sure that all are listed, each with a separate Signed-off-by
line.
We have codified our coding guidelines in GNU Radio GREP1. Please read them, and stick to them. For C/C++ code, use clang-format. For Python, PEP8 is your friend (but again, check the actual coding guidelines).
We follow standard git commit message guidelines, similar to many other open source projects. See the coding guidelines for more details. In a nutshell:
- Keep the lines below 72 characters
- Subject line has the component prepended (e.g.,
kernelname:) - Avoid empty git commit messages
- The git commit message explains the change, the code only explains the current state
VOLK unit tests compare the results of each kernel version to the generic version. Keep the generic kernel version as simple as possible and verify your optimized kernels against the generic version.
When you've submitted a pull request, please take the time to review another one. This helps make sure that there are always a number of reviews at least equal to the number of pull requests, which means the maintainers don't get overwhelmed when a lot is being contributed.
When writing programs that are executable from the command line, please follow existing examples regarding their command line arguments, and reuse them.