Skip to content

Latest commit

 

History

History
299 lines (211 loc) · 10.8 KB

CONTRIBUTING.md

File metadata and controls

299 lines (211 loc) · 10.8 KB
Raw

Contributing to Yaru

Yaru consists of one project with 4 distinct parts.

  • gnome-shell directory is the theme for GNOME Shell. This themes stuff like the calendar widget, the Ubuntu dock, the top panel, the login screen and more. It derives from upstream GNOME Shell theme.
  • gtk contains the themes GTK+2 and GTK+3. This specifies how applications like Files, Terminal, Ubuntu Software look. It derives from upstream Adwaita GTK+2 and GTK+3 themes.
  • sound contains all sound themes related information, combining both WoodenBeaver and Touch-Remix.
  • icon-theme contains all the icons, derives from the Suru icon theme.

Build and install themes from source

This installation method is to try out the theme while developing it. If you're not a developer, follow the instructions in the README.md.

Needed packages to clone the repository and build the source files

sudo apt install libgtk-3-dev git meson sassc

Download the repository from github

git clone https://github.com/ubuntu/yaru.git
cd yaru
# Initialize build system (only required once per repo)
meson build
cd build
# Build and install
sudo ninja install

Useful one-liners for icon theme contributors

# Additionally installs packages needed to work on the icon theme
sudo apt install libgtk-3-dev git meson sassc inkscape optipng ruby

If you want to change the GDM look and point to the same stylesheet. You only need to do this once.

update-alternatives --install /usr/share/gnome-shell/theme/gdm.css gdm.css /usr/share/gnome-shell/theme/Yaru/gnome-shell.css 15

# Otherwise using a gresource file
update-alternatives --install /usr/share/gnome-shell/gdm-theme.gresource gdm-theme.gresource /usr/share/gnome-shell/theme/Yaru/gnome-shell-theme.gresource 15

If you reboot, select the Yaru session in GDM and you should be all right.

Help to install Gtk4 and Libadwaita

If you want to test the Gtk4 theme, you need to install Gtk4 (and eventually Libadwaita).

Install Gtk4

Just install libgtk-4-dev package (Ubuntu >= 21.10 only):

sudo apt install libgtk-4-dev
Install from source (Ubuntu <= 21.04) Firstly clone the repository: ```console git clone https://gitlab.gnome.org/GNOME/gtk.git ```

Then, you need to install dependencies (please report if more ones are needed):

sudo apt install sassc clang libglib2.0-dev libcairo2-dev libpango1.0-dev libgdk-pixbuf-2.0-dev libepoxy-dev libxkbcommon-dev libgraphene-1.0-dev cmake libwayland-dev libxrandr-dev libxi-dev

And finally compile using meson:

cd gtk
meson --prefix=/usr --sysconfdir=/etc --localstatedir=/var --libdir=lib/x86_64-linux-gnu _build .
cd _build
ninja
sudo ninja install

Now you can use the gtk4-widget-factory app.

Install Libadwaita

Awaiting an official Ubuntu packaging, you need to install libadwaita from source.

Firstly clone the repository:

git clone https://gitlab.gnome.org/GNOME/libadwaita.git

Then, you need to install dependencies (please report if more ones are needed):

sudo apt install sassc valac libglib2.0-dev

And finally compile using meson:

cd libadwaita
meson --prefix=/usr --sysconfdir=/etc --localstatedir=/var --libdir=lib/x86_64-linux-gnu _build .
cd _build
ninja
sudo ninja install

Now you can run the adwaita-1-demo using the console:

adwaita-1-demo

Note: regardless of your current gtk theme, adwaita-1-demo use Adwaita by default. You must switch to Yaru using the gtk inspector.

Build .deb files from source

  • Install debian-packaging-tools packages:
sudo apt install debhelper dh-migrations libgtk-3-dev git meson sassc
  • Download this repository from github:
git clone https://github.com/ubuntu/yaru.git
  • Building binary debian-packages for testing:
#Inside yaru directory
cd yaru
#Building binary debian files
dpkg-buildpackage --build=binary -uc -us -tc
  • Installing deb(s):
#Leaving yaru directory
cd ..
#Installing all generated .deb(s)
sudo dpkg -i yaru-theme-*.deb

More granular changes

Now everything should be in place. Select the GTK, icon and sound theme via:

gsettings set org.gnome.desktop.interface gtk-theme Yaru
gsettings set org.gnome.desktop.sound theme-name Yaru
gsettings set org.gnome.desktop.interface icon-theme Yaru

The GTK2, GTK3 and GTK4 files go into /usr/local/share/themes/Yaru. The shell files go into /usr/local/share/gnome-shell/theme/Yaru. You can edit the gtk.css and gnome-shell.css files in those folders directly for testing, or you can edit the SCSS files inside the folder you cloned from GitHub.

SCSS is the actual "source code" of the theme. This is compiled into the CSS files. Edit the SCSS if you want to contribute your changes back to us. SCSS is simple enough to get the hang of if you already know CSS. You can go through this SCSS tutorial to learn more. After making your edits in the SCSS files, you can run sudo ninja install in the yaru/build folder. That’ll do all the compiling and installing.

Changes to Gnome Shell theme are visible after doing Alt + F2 and running r as command. The changes to GTK theme will be visible after running the following commands.

# To reload GTK theme
# Change to Adwaita theme and back to Yaru
gsettings set org.gnome.desktop.interface gtk-theme Adwaita
gsettings set org.gnome.desktop.interface gtk-theme Yaru
# To reload icon theme
# Change to Humanity icon theme and back to Yaru
gsettings set org.gnome.desktop.interface icon-theme Humanity
gsettings set org.gnome.desktop.interface icon-theme Yaru

Testing desktop-login sound

Type in a terminal gnome-session-properties. It'll give you the list of starting applications. Click on "add", and type the following informations in the dialog shown :

  • Name: GNOME Login Sound

  • Command: /usr/bin/canberra-gtk-play --id="desktop-login" --description="GNOME Login"

  • Comment: Plays a sound whenever you log in

Testing from the desktop

A quick and easy way to test if the sounds are installed correctly, is by triggering them from the desktop. Here's a few places that will trigger a notification:

  • Open a texteditor (like Gedit or even the terminal) and press backspace or delete
  • Open two tabs in Firefox and close the window
  • Adding / removing a USB drive
  • Clicking the volumeslider in the system menu in the top right corner

Quick testing in the GTK Inspector

To do some quick testing you can also use the GTK Inspector.

# Install inspector
sudo apt install libgtk-3-dev
# Enable the shortcut to open it
gsettings set org.gtk.Settings.Debug enable-inspector-keybinding true

Now you can open any program GTK3 program and press CTRL + Shift + D to bring up the inspector.

The most useful program to use with the inspector is the widget factory though. Which shows you basically every widget. Run sudo apt install gtk-3-examples, then run gtk3-widget-factory That will open the widget factory, then you can open the inspector with CTRL + Shift + D again.

Click the upper-left target button to select an object.

Select something like a button and you’ll see the following.

We don’t really care too much about that stuff so just click the dropdown button with “Miscellaneous” and select CSS nodes. Which shows you:

The element you selected will be highlighted within a list of all elements in the window. In the left pane you can see the name of the widget you clicked on (button) and its different CSS classes (.text-button .toggle). The right pane shows all the element’s CSS properties and values and where to find it in the gtk.css file. You can see all supported CSS properties in the inspector, but for something more detailed look at the Gnome CSS Properties reference.

Clicking the CSS tab will take you to a text entry window where you can type in CSS that will be applied.

Putting button { background: orange; } will make all buttons have a orange background. It’s exactly like the inspect element tool in a web browser.

Why do we import from package content and not from upstream git repository?

We sync our version to be compatible with the GTK and GNOME Shell versions being in ubuntu repositories. This is why we sync from them (or rebase them as soon as we update a new version with changes in ubuntu).

GTK: What is removed from the initial directory?

We remove on new version import:

  • *.in, Makefile.*, meson.build: we have our own build system.
  • adwaita_engine.c: we use the default adwaita engine
  • *.css: we build these from the *.scss sources

Get your copy of Yaru and make a Pull Request (PR)

On our GitHub page (where you are probably reading this), fork the Yaru repository, then clone your copy locally on your computer and build it for the first time to verify that everyting is in place.

git clone https://github.com/yourusername/yaru.git
cd yaru
meson build
sudo -i -H ninja install -C build

now create a feature branch for development

git checkout -b branch-name

A good branch name should recall the intended change; if it is a fix for a bug with number 1234 a good name could be something like issue1234/fix-for-something

Once you are done with your work, use git status to see the list of changed (and eventually new) files and stage them with git add and commit your work with git commit

$ git status
On branch issue1234/fix-for-something
Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git checkout -- <file>..." to discard changes in working directory)

        modified:   CONTRIBUTING.md
...
$ git add CONTRIBUTING.md
$ git commit

Now think about a good commit message. The expected format is like the following

short explaination of the commit

A more detailed explaination, possibly explaining the current state, why a change is needed and how you implemented the change. Try to find a good compromise between too short and too long.

if it is a fix for a bug numbered 1234 inform GitHub system so that it can close it automatically when the PR is merged.

closes #1234

Finally, make a Pull Request (PR) from branch-name

git push --set-upstream origin add-git-workflow

Open Yaru GitHub repository page, a link to "Create your Pull request" should appear on the main page