CONTRIBUTING.md

Contribute to Black Box

Thank you for considering contributing to Black Box!

This guide aims to make it easier for us to communicate and further develop Black Box.

You can contribute in many ways: reporting bugs, providing feedback, translating the app, or writing code.

Plan ahead

If you plan to develop a new feature for Black Box, open a feature request first. This ensures we can discuss the idea and the implementation beforehand. Remember that not all feature requests will be accepted, as some might diverge from Black Box's philosophy.

Bugs and Feature Requests

Black Box has templates for bugs and feature requests. Please use them!

• Feature request
• Bug report
• Security issue - make sure "confidential" is checked

Translating

Black Box is accepting translations through Weblate! If you'd like to contribute with translations, visit the Weblate project.

Writing Code

Before writing code, make sure you have followed these instructions.

Setup

I recommend using Visual Studio Code with the following extensions:

• Vala
• Editorconfig
• Flatpak

Code Style

Black Box follows the Prettier code style as much as possible. With one exception: brace style.

public class Terminal.YourClass : YourParent {
  construct {
    // ...
  }

  public YourClass () {
    Object ();

    this.notify ["my-change"].connect (this.my_callback);
  }

  private void my_callback (
    int x,
    int y,
    int n_times
  ) {
    if (x < 0) {
      // ...
    }
    else if (x > 9) {
      // ...
    }
    else {
      // ...
      try {
        // ...
      }
      catch (Error e) {
        // ...
      }
    }
  }
}

Reactivity

Avoid using notify to update the UI as much as possible. Using GLib.Settings.bind, GLib.Settings.bind_with_mapping, or GLib.Object.bind_property is preferred.

Warnings

Do your best not to introduce new compilation or runtime warnings to the app. Warnings make it harder to debug errors and give users the impression that the app is not working as it should.