Contributing

Contributing can be highly rewarding, but it can also be frustrating at times. It takes time to review patches, and as this is an open source project, that sometimes can take a while. The reviewing process depends on the availability of the maintainers, who may not be always available. Please try to be understanding throught the process.

There a few guidelines you need to keep in mind when contributing. Please have a look at them as that will make the contribution process easier for all parties.

Commits

Git history is very important to the openinput project. The git history is not only a code versioning tool, but also documentation. It should describe how the code changed and why. Someone should be able to relatively easily undertand the code progress by reading the git history.

For this reason, we will not accept big “code-dump” patches. Every commit should be an unique logical change, and should be acompanied with an appropriate description.

Hint

Look at the current git history to have a better idea of what is supposed to look like!

Format

We adopt the following commit format:

component: description

component is the code component (docs, readme, platform/stm32f1, target/stm32f1-generic, etc.). If your commit touches several components, use the one the original logical change belongs to.

description is a descriptive summary of the change, why it is needed, and any non-obvious missing context.

Hint

If you are not sure what to use as the component prefix, look at the git history for the file in question.

If the commit is not trivial, or involves some context, you should write a summary in the commit body.

See the following example:

hal: pass hid_interface_t as void* to hid_send

   hid_interface_t may be an incomplete type and the compiler does not seem
   happy about that.

   Signed-off-by: Filipe Laíns <lains@riseup.net>

Hint

When unsure how to structure your commit or what description to use, please ask a maintainer.

Workflow

While working on openinput, we recommend using the following workflow.

Creating a commit

After writing your code, you should you stage the relevant changes using:

git add -p

This will allow you to select which changes you actually want to include in the commit. You will be prompt with code hunk and a menu to select what you want to do. There are several options:

y - stage this hunk
n - do not stage this hunk
q - quit; do not stage this hunk or any of the remaining ones
a - stage this hunk and all later hunks in the file
d - do not stage this hunk or any of the later hunks in the file
s - split the current hunk into smaller hunks
e - manually edit the current hunk
? - print help

After selecting all relevent bits of the code, you should commit.

git commit

Fixing a commit

If you made any mistake in a commit, we recommend using fixup commits. It goes as follows. You make the changes you want to add to the commit and then stage them.

git add -p

After this, instead of commiting this change as a separate commit, we commit it as a fixup commit for the commit you want to fix (in the example, HEAD~1, it can be replaced by a commit hash or other kind of commit reference).

git commit --fixup HEAD~1

After this we can squash the fixup commit with the original commit by rebasing.

git rebase --autosquash --interactive origin/main

Hint

If you are new to rebases, we recommend you to have a look at the Rebasing page of the git documentation.