Skip to content

Latest commit

 

History

History
182 lines (127 loc) · 6.01 KB

CONTRIBUTING.md

File metadata and controls

182 lines (127 loc) · 6.01 KB
Raw

Contributing

Thank you for considering contributing to this project. It means that you not only find it useful, but that you think there's something that could be done to make it more useful, or useful to more people.

The goal is to create an implementation of KDE Connect that integrates with the GNOME desktop more than is appropriate for the original implementation.

Code of Conduct

While taking part in this project, all that is required is to stay on topic.

Note that you are still bound by the Code of Conduct for whichever platform you use to access the project repository.

Overview

This document is mostly about code contributions. There are pages in the Wiki for Translating, Theming and Packaging. You can open a New Issue or Pull Request for anything you like and it will be reviewed.

Code Guidelines

  • Code MUST be written in GJS if at all possible

    Obvious exceptions are code that help integrate with other programs, like the Nautilus extension.

  • Code MUST run anywhere GNOME Shell runs

    It is acceptable and sometimes necessary to use resources that may be specific to Linux, but fallbacks must be available for other systems like BSD. Virtual machines may be supported, but not at any expense to real systems.

  • Code MUST NOT break compatibility with the KDE Connect project

    Under no circumstances may code break protocol compatibility or introduce new protocol features. Any protocol related discussion must happen directly with the KDE Connect team and changes or additions are subject to their approval.

Code Style

GSConnect ships with an ESLint file, which is run on all code by the CI and can be run on code simply with eslint src/. When in doubt, copy the existing code style.

Developing

Architecture

GSConnect is composed of three relatively distinct components:

  • Service (/service)

    The service runs as a separate process in the background and does all the heavy lifting, including connecting and communicating with remote devices. It also exposes several DBus interfaces.

  • Shell Extension (extension.js, /shell)

    The GNOME Shell extension controls starting and stopping the service, and consumes the DBus interfaces exposed by the service. It also helps GSConnect to integrate into GNOME Shell.

  • Preferences (gsconnect-preferences, /preferences)

    Unlike most extensions, GSConnect has it's own process for configuring the service and devices, which also communicates with the service over DBus.

Building and Installing

GSConnect uses a meson build system which can accomodate system or user installs. Typically, GSConnect should be developed and installed as a user extension, while support for system installs exists primarily for distributions that want to package GSConnect.

User Install

When installing as a user extension, GSConnect will try its best to detect necessary paths and automatically install required files required for the service to run. The example below will build a user extension ZIP, then install it:

$ meson _build
$ ninja -C _build install-zip

Use the make-zip target instead to simple build a distributable ZIP, which will be output as _build/gsconnect@andyholmes.github.io.zip:

$ meson _build
$ ninja -C _build make-zip

System Install

When installing as a system extension, the build must be configured to ensure GSConnect can function properly when run (details in meson_options.txt). Below is a typical example for Fedora:

$ meson --prefix=/usr \
        --libdir=lib/ \
        -Dgnome_shell_libdir=/usr/lib64/ \
        -Dfirewalld=true \
        _build
$ ninja -C _build install

Typical Workflow

The typical workflow for developing GSConnect will mainly involve working on the service. First build and install the extension:

$ meson _build
$ ninja -C _build install-zip

Next restart GNOME Shell and enable the extension. While developing you should enable debugging output and watch the output with journalctl:

$ dconf write /org/gnome/shell/extensions/gsconnect/debug true
$ journalctl -f -o cat /usr/bin/gjs

After making changes to the service, you should run the install-zip target again. The service will automatically restart and there is no need to restart GNOME Shell unless you have made changes to the shell extension:

$ ninja -C _build install-zip

Preferences

When working on the Preferences application, you must close and reopen the window after running the install-zip target. You can use journalctl to watch the output or if it's more convenient simply run the application from the shell:

$ cd ~/.local/share/gnome-shell/extensions/gsconnect@andyholmes.github.io
$ ./gsconnect-preferences

Shell Extension

When developing the Shell extension, you must restart GNOME Shell after making any changes. Note that the debug() function is not available in the Shell extension and you should watch gnome-shell with journalctl instead of GJS:

$ journalctl -f -o cat /usr/bin/gnome-shell

Questions

For general discussion, there is an IRC/Matrix channel for GSConnect:

If that's not convenient, discussion can happen in the comments to your Pull Request or you can open a New Issue for more public discussion and mark the Pull Request as a fix for it.