Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
220 lines (147 loc) · 7.98 KB

CONTRIBUTING.md

File metadata and controls

220 lines (147 loc) · 7.98 KB

Welcome! Thanks for looking into contributing to our project!

Table of Contents

Ways to Contribute

This document below primarily focuses on writing code for this project, but there are many different ways you can help out:

  • Testing: We only have access to a limited set of hardware and accounts. Installing the project and using it yourself is a great way to get us more feedback to improve the project.

  • Writing UI implementations: The UI included in this document is for reference purposes. We need developers who are familiar with (or willing to learn about) the specifics of integrating with particular desktop environments, like GNOME, KDE, etc.

  • Writing documentation: Documentation is always hard. If you notice something missing or incorrect, then feel free to ask a question about it or send a pull request to address it.

  • Sponsorship: We haven't set up any sort of platform to receive monetary donations, but if you are interested, you can reach out by filing an issue, and we can see what we can do. Individual sponsorships are not the only way to support the project: getting us in touch with companies or foundations offering grants for open source or hardware for testing is also helpful.

  • Spread the word: We believe that this project is important to get in the hands of users. Whether you can help or not, telling others about the project and asking them to get involved is another way you can help!

And then there is, of course, writing code!

Looking for Help?

Here is a list of helpful resources you can consult:

Discussion platform

Join the discussion on Matrix at #credentials-for-linux:matrix.org.

Documentation

To help you get started, we have provided documentation for various parts of the project. Take a look at these:

You may also need to consult various specifications while developing.

Reporting Issues

If you find any bugs, inconsistencies or other problems, feel free to submit a GitHub issue.

Also, if you have trouble getting on board, let us know so we can help future contributors to the project overcome that hurdle too.

Security Issues

If you are reporting a security issue, please review SECURITY.md for the prodedure to follow.

Submitting Code

Ready to write some code? Great! Here are some guidelines to follow to help you on your way:

Building

When you first start making changes, make sure you can build the code and run the tests.

To build the project, follow the build instructions in BUILDING.md.

To run tests, follow the test instructions in the same file.

Coding Style

In general, try to replicate the coding style that is already present. Specifically:

Naming

For internal consistency, credentialsd uses snake_case for D-Bus field names and SCREAMING_SNAKE_CASE for enum values. This is consistent with D-Bus conventions, but it is distinct from Web Credential Management/WebAuthn conventions, which this API is based on. Values specified within JSON string payloads should stick to the naming conventions as documented in the WebAuthn spec.

Code Formatting and Linting

For Rust code, we use rustfmt to ensure consistent formatting code and clippy to catch common mistakes not caught by the compiler.

# if you don't have them installed, install or update the stable toolchain
rustup install stable
# … and install prebuilt rustfmt and clippy executables (available for most platforms)
rustup component add rustfmt clippy

Before committing your changes, run cargo fmt to format the code (if your editor / IDE isn't set up to run it automatically) and cargo clippy to run lints. You'll need to run this from each Cargo project (credentialsd/, credentialsd-ui/, credentialsd-common/).

For Python code, we use ruff.

Import Formatting

Organize your imports into three groups separated by blank lines:

  1. std imports
  2. External imports (from other crates)
  3. Local imports (crate::, super::, self:: and things like LocalEnum::*)

For example,

use std::collections::HashMap;

use credentialsd_common::model::Operation;

use super::MyType;

Commit Messages

The commit message should start with the area that is affected by the change, which is usually the name of the folder without the credentialsd- prefix. The exception is credentialsd/ itself, which should use daemon.

Write commit messages using the imperative mood, as if completing the sentence: "If applied, this commit will ___." For example, use "Fix some bug" instead of "Fixed some bug" or "Add a feature" instead of "Added a feature".

Some examples:

  • "daemon: Allow clients to cancel their own requests"
  • "ui: Allow users to go back to device selection"

(Take a look at this blog post for more information on writing good commit messages.)

Tracking Changes

For bug fixes, breaking changes and improvements add an entry about them to the changelog.

If your changes affect the the public D-Bus API (Gateway, Flow Control or UI Control APIs), also make sure to document the change in doc/api.md and add a note to the revision history in that file.

Submitting PRs

Once you're ready to submit your code, create a pull request, and one of our maintainers will review it. Once your PR has passed review, a maintainer will merge the request and you're done! 🎉

Where do I start?

If this is your first contribution to the project, we recommend taking a look at one of the open issues we've marked for new contributors.

Testing

Before committing, run meson test --interactive from the build/ directory to make sure that your changes can build and pass all tests, as well as running the formatting and linting tools mentioned above.

You should also follow the install instructions in BUILDING.md and execute authentication flows in a browser to ensure that everything still works as it should.

Translations

credentialsd-ui is using gettext-rs to translate user-facing strings.

Please wrap all user-facing messages in gettext("my string")-calls and add the files you add them to, to credentialsd-ui/po/POTFILES.

If you introduce a new language, also add them to credentialsd-ui/po/LINGUAS.

Then cd into your build-directory (e.g. build/) and run

    # To update the POT template file, in case new strings have been added in the sources
    meson compile credentialsd-ui-pot
    # and to update the individual language files
    meson compile credentialsd-ui-update-po

to update the template, so it contains all messages to be translated.

Meson should take care of building the translations.

When using the development-profile to build, meson will use the locally built translations.