Setting up the environment

In order to start hacking the project you can either:

• use the pre-configured dev container, which contains all the needed pieces of software. It also maps the user extension installation path inside the container to ease the deployment.
• have Node.js and Yarn (classic) installed, plus the following additional tools required by the build process:
  • gettext, for translation processing
  • jq, for json processing
  • yq, for yaml processing
  • rsync, to deploy locally the extension
  • zip, to create the final zip package

Cloning the repository

Clone the repository in a directory of your choice:

git clone git@github.com:mackdk/gnome-github-manager.git

Use your own fork, if you made one.

Installing yarn and the software dependencies

First you need to install Yarn through the node package manager:

sudo npm install --global yarn

If you prefer, you can avoid installing it as root by changing the default npm's directory

Once yarn is available, you need to retrieve the code depenendecies. So from the root of you local repository clone do:

yarn install

Now you are ready to build the extension for the first time. The command to do that is:

yarn build

Working with the extension

The following yarn commands are available to ease the development process:

• Base commands:
  • clean: removes all the built artificats.
  • compile: executes Rollup to compile all TypeScript code and build the extension. The result of the compilation is available in the folder build/dist.
  • lint: performs static analysis on the TypeScript source code using eslint.
  • sync: copies the compiled code to the local extension folder ~/.local/share/gnome-shell/extensions/. Then by restarting GNOME you will be able to run the with your latest changes.
  • updateTranslations: Updates the pot template with the latest strings to translate.
  • followLogs: show the log entries written by the extension. See the logging page for more pieces of information. Please note that this task does currently not work within the dev container.
  • createZip: create the zip archive for distribution.
• Composite commands:
  • build: compiles and updates the translations.
  • deploy: compiles, updates the translations and sync the extension to the local extensions folder.
  • package: compiles, updates the translations and create the zip archive.

When using Wayland, to run the extension after a deployment without having to restart the Gnome Shell, a nested session can be spawned using the following command:

$> dbus-run-session -- gnome-shell --nested --wayland

Directory Structure

The code is organized following losely the Maven directory structure. Thus, all the source code is inside the src folder, organized by scope and type.

• main: all the sources that will end in the final compiled extension.
  • po: translation files.
  • resources: icons, metadata, ui files and GLib schemas.
  • types: TypeScript types definitions for external JavaScript libraries.
  • typescript: actual extension source code.
• support: extensions and tools needed during the build process of the extension.
  • typescript: support code written in TypeScript.