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

Steps to add a new translation:

1. run meson build
2. add the language code you wish to translate to po/LINGUAS
3. run ninja -C build blackbox-update-po
4. a new file po/<language_code>.po will have been created
5. start translating

Steps to update a translation:

1. run ninja -C build blackbox-update-po
2. update po/<language_code>.po

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.