Setting up the environment

In order to start hacking the project you need to have installed Node.js and Yarn (classic). Moreover, the build process requires these additional tools:

• gettext, for translation processing
• jq, for json processing
• rsync, to deploy locally the extension
• zip, to create the final zip package

Installing the prerequisites

Depending on your distribution, you should install the all the packages mentioned above. Here are the commands that you can use for commonly used distributions:

openSUSE:

sudo zypper install git nodejs18 gettext-tools jq rsync zip

Fedora:

sudo dnf install jq git gettext nodejs rsync zip

Ubuntu:

sudo apt-get install jq git gettext nodejs npm rsync zip

Archlinux:

sudo pacman -S jq git gettext nodejs-lts-hydrogen npm rsync zip

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.
  • 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.

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.