Contributing

xNVMe is hosted on GitHUB where you can raise issues, start a discussions, or set up a pull-request for contributing your changes. This page contains information related to the latter. Specifically, the Contribution Process is of relevance to you and the Toolbox available for development.

In addition to GitHUB then you can join Discord, there you can ping for feedback on your pull-request or ask questions.

Contribution Process

  • Fork the xNVMe repository on GitHUB

  • Make your changes, push them to you fork and create a pull-request

    • The pull-request should target the next branch

    • If you just want feedback/WIP then set up the pull-request as a Draft

  • The CI will trigger in as you create the PR and re-triggered upon update

    • The default CI-jobs consists of running style/linters and building xNVMe

    • When ready for integration it will be marked pr-ready-for-test and a larger suite of functional tests are triggered

Commit Messages

  1. The first line is subject/title

    • Keep it at a max. of 72 chars, if possible

    • Prefix with the compoent e.g. be:linux: fix error-handling

    • Lower-case is preferred

    • Use the “imperative mood” e.g. fix rather fixes/fixed

    • Do not end with a punctuation

  2. Then an empty line.

  3. Then a description (may be omitted for truly trivial changes).

    • Should explain what and why not how

  4. Then an empty line again (if it has a description).

  5. Then a Signed-off-by tag with your real name and email.

    • For example: Signed-off-by: Foo Bar <foo.bar@example.com>

    • Use git commit -s ... to add the sign-off automatically

Toolbox

Supporting the developtment of xNVMe is a toolbox with a collection of scripts in Python, Bash and a Makefile to instrument it. See section Makefile helper for a description of it.

For common linter/format tooling then the pre-commit framework is used and described in section Pre-commit / Git-hooks.

Makefile helper

As described in sec-getting_started, then xNVMe uses Meson, however, during development usage of the Toolbox is invoked via make based on the Makefile in the root of the xNVMe repository.

The Makefile contains a bunch of helper-targets. Invoking make help provides a brief description of what is available:

Usage:
 
  make help          ; Brief target description
  make help-verbose  ; Verbose target descriptions
  make [target]      ; Invoke the given 'target'
 
Targets:
 
build                ; Build xNVMe with Meson
build-deb            ; Build a binary DEB package
clean                ; Remove Meson builddir
clean-subprojects    ; Remove Meson builddir as well as running 'make clean' in all subprojects 
clobber              ; invoke 'make clean' and: remove subproject builds, git-clean and git-checkout .
config               ; Configure Meson
config-debug         ; Configure Meson to compile xNVMe with '--buildtype=debug'
config-slim          ; Configure Meson to compile xNVMe without subprojects (SPDK, fio, liburing)
config-uring         ; Configure Meson to compile xNVMe with liburing as the only backend
default              ; invoke: 'make info', 'make tags', 'make git-setup', 'make config' and 'make build'
format               ; run code format (style, code-conventions and language-integrity) on staged changes
format-all           ; run code format (style, code-conventions and language-integrity) on staged and committed changes
gen-bash-completions ; Helper-target to produce Bash-completions for tools (tools, examples, tests)
gen-libconf          ; Helper-target generating third-party/subproject/os/library-configuration string
gen-man-pages        ; Helper-target to produce man pages for tools (tools, examples, tests)
gen-src-archive      ; Helper-target to produce full-source archive
git-setup            ; Do git config for: 'core.hooksPath' and 'blame.ignoreRevsFile'
help                 ; Print the description of every target
help-verbose         ; Print the verbose description of every target
info                 ; Print information relevant to xNVMe
install              ; Install xNVMe with Meson
install-deb          ; Install the binary DEB package created with: make build-deb
tags                 ; Helper-target to produce tags
tags-xnvme-public    ; Make tags for public APIs
uninstall            ; Uninstall xNVMe with Meson
uninstall-deb        ; Uninstall xNVMe with apt-get

Pre-commit / Git-hooks

xNVMe utilizes the pre-commit framework for wrapping various code-format and linters tools. You can enable it to run via git-hooks or invoke it manually via the Makefile helper e.g.:

# format all files
make format-all

# format only files with staged changes
make format