Contribute

Contributions to OpenSync are encouraged. These can include new features, enhancements, bug fixes, or customizations/patches for particular chipsets or platforms.

1 Licensing of Contributions
2 Development Model
3 General Rules
4 Bug Fixes
5 Features
- 5.1 Feature Branches
- 5.2 Functionality Isolation
6 Writing Commit Messages
7 Consistent Identity

Licensing of Contributions

To protect the project and all stakeholders (contributors as well as adopters), the contributors must agree to project’s Contributor License Agreement.

By submitting a contribution, you accept the terms and conditions of the following Contributor License Agreement:

Development Model

The development model used for the public OpenSync repositories is ‘stable master’ with feature branches and pull requests.

Additionally, the maintainers choose to keep a linear history. This means that, whenever possible, feature branches and fixes are rebased to the tip of the master branch, rather than merged using merge commits.

General Rules

A commit should never include more than one change, i.e. it must not contain unrelated changes (be it functional or cosmetic).

Newly added code must conform to the coding style and other recommendations in the OpenSync Coding Standard.

Note however, that coding styles should not be mixed, therefore small changes in existing files should be made using whatever style is present, to seamlessly blend in with the surrounding code.

If a feature or a fix requires changes in more than one repository, the pull requests must be cross-linked, so that they can be handled as a whole.

Before pushing a commit, always examine the entire diff (using `git show` or a Git GUI client of your choice). Examining the diff often reveals unintended changes. During such ‘double checks’, one may even spot a bug. After examining the diff, re-read the commit message and make sure it properly reflects the changes included in the commit (see also Writing Commit Messages below).

Bug Fixes

In most cases, a single commit is sufficient for a bug fix. If several commits were made during the development and testing of the fix, they should be squashed into a single commit before creating a pull request.

For modifications that are not pure fixes and have potential side effects, add a “Risks:” section in the commit message, describing the possible side effects and the rationale behind any settings or tradeoff decisions.

For bugfix commits, it is recommended to add a “Fixes:” trailer at the end of the commit message. This helps the maintainers when determining which fixes are applicable to older “longterm” releases.

Use `git log --abbrev=12 --format='Fixes: %h ("%s")' -1 <faulty_commit>` to format the trailer line.

Features

When adding features to OpenSync, various aspects must be considered, like keeping APIs and the architecture stable and future-proof. To prevent uncoordinated efforts, we recommend you to contact OpenSync maintainers (contact: info@opensync.io) during the design phase.

Feature Branches

When developing larger features, it is often beneficial to develop – and also commit – the changes in stages, e.g.:

‘Refactor the existing code to prepare it for infrastructural changes’
‘Add infrastructure for the new functionality’
‘Add actual features using the new infrastructure’

This makes it easier to review the changes, results in cleaner git history, and may also be beneficial if it becomes necessary to drill down into the history when analyzing bugs (or even use bisection with actual firmware builds). Cleaner history also means that if conflicts are encountered when merging or rebasing, they are easier to resolve.

If additional fixes of earlier commits are needed – either during development, or during a pull request review – they should be squashed into respective commits using interactive rebase.

Functionality Isolation

Every non-essential functionality (that is, not required for the most basic operation) must be isolated using kconfig symbols. This allows vendors to disable the functionalities they do not require. Before submitting a pull request, the code must be compiled and tested both with the new functionality enabled, as well as with the new functionality disabled.

Writing Commit Messages

Title

The first line is a title (or ‘subject line’). Capitalize the first word, do not end the title with a period.
It is recommended to keep the title less than 50 characters long.
When applicable, start the title with a module name, followed by a colon (e.g.: “osn: ...”).

Body

The title and the body (detailed description) must be separated by a blank line.
The body must be wrapped at 72 characters (except for quoted snippets).
Describe what and why, not how. Tell a story, so that others can understand the reasons and the rationale behind the change.
For bugs, describe not just the cause, but also symptoms, circumstances, user impact, etc. Add snippets when applicable (e.g.: error backtrace, kernel log) and use “...” to indicate any cutouts. Describe the sequence of events after the snippet.
Ideally, the first paragraph of the body should be a short summary, suitable for direct inclusion in release notes.

Add-ons (trailers)

When applicable, add the “Fixes:” trailer (described above).
‘Sign-off’ each commit (using the ‘-s’ option, which adds the “Signed-off-by:” trailer).
NOTE: Additional ‘sign-offs’ may be added as a commit is processed.

Consistent Identity

Before creating any commits, verify that your name and email in ~/.gitconfig and on GitHub match (https://github.com/settings/profile).