Ouroboros Contributions

Ouroboros is far from complete. Plenty of things need to be researched and implemented. We don’t really keep a list, but this kanban board can give you some ideas of what is still on our mind and where you may be able to contribute. Our coding guidelines can be found in the Source Code Guide.

Contact

There are 2 ways that are used to communicate.

For daily chat we use a matrix space bridged to a public slack channel. Use the tool you prefer and whatever login name you desire. Just hop on and ask away.

The mailing list is mostly used for sending software patches, but can be used to contact us about almost anything. Participation requires you to register for this list.

Bug reports

Bugs are reported through our Bugzilla issue tracker, or alternatively via GitHub.

When reporting bugs, check if the bug is still present in the 'be' branch, and try to include the following:

• Provide a description of the bug
• Provide system logs of the IRMd and IPCPs
• Provide a minimal code example to reproduce the bug
• Sync with the HEAD of the most stable branch where the bug is present
• Provide a bug fix if you can, send a patch to the mailing list

Feature requests

New features can be always be requested through the mailing list or alternatively GitHub. They will be taken into account when a next version of the prototype is discussed.

Contributions

Patches

Git patches can be sent to the mailing list. You will need to use an email address that is registered to the mailing list. Sending commits by mail can be done with git send-email, which might need to be installed separately.

To set this up, open your git config

git config --global --edit

and add your email settings, e.g. for a gmail account (don't forget to edit your email address in this snippet):

[sendemail]
    smtpserver = smtp.googlemail.com
    smtpencryption = tls
    smtpserverport = 587
    smtpuser = youremail@ymail.com
    confirm=auto

For other email providers it is similar.

When this is set up, the last commit on the current branch is sent as a patch from the command line using git send-email:

git send-email -1 --to=ouroboros@freelists.org

Commit messages

A commit message should follow these 10 simple rules, based on Chris Beams' excellent guide.

• Separate subject from body with a blank line
• Limit the subject line to 50 characters
• Capitalize the subject line
• Do not end the subject line with a period
• Use the imperative mood in the subject line
• Precede the subject line by indicating the component where changes were made
• Wrap the body at 72 characters
• Use the body to explain what and why vs. how
• If the commit addresses a bug, reference it in the body
• Sign off your commits using the signoff feature in git

Here is an example of a change in the lib/ folder:

lib: Add support for Linux RTT estimator

This adds the option to use the Round-Trip-Time (RTT) estimation
algorithm as it is implemented in the TCP implementation in Linux. It
looks like it outperforms the TCP default algorithm, so I enabled this
one by default. Also adds the option to change the RTO timeout
calculation to include more (or less) than 4 times the mdev (specified
as a power of 2. Left the default value to 2 (so, 4 mdevs), but 3 (8
mdevs) gives better results in my tests.

Signed-off-by: Dimitri Staessens <dimitri@ouroboros.rocks>

Versioning

Git is used as a version tooling for the code. Releases are identified through a git tag by a number MAJOR.MICRO.PATCHLEVEL.

• Incrementing MAJOR is done to indicate a big step ahead in terms of features; it is discussed when new features are planned.
• Incrementing MICRO is done when APIs/ABIs are not necessarily compatible.
• The PATCHLEVEL is incremented when an urgent bugfix is incorporated.

Version 1.0.0 would be the first minimum viable prototype version.

Repository structure

The main git repository can be found at: https://ouroboros.rocks/cgit/ouroboros

It contains the following branches:

• master: Contains the most stable versions of Ouroboros.
• testing: Contains tested code but may still contain bugs.
• be: Contains untested but compiling code.

All new contributions are integrated into ‘be’ through patches sent to the mailing list. Once a version of ‘be’ is tested enough, it is merged into ‘testing’. When a ‘testing’ version is considered stable enough, it is merged into ‘master’. Most users should probably use master.

New development is always done against the ‘be’ branch of the main git repository. Contributions are always made using your real name and real e-mail address.