From 2e7f2569a04751964a821e56267814fbd63a0fa9 Mon Sep 17 00:00:00 2001 From: Adam Setch Date: Wed, 14 Oct 2026 07:46:51 -0400 Subject: [PATCH 1/5] docs: add emoji headings and a contributing guide Applies the organization's approved README heading emoji convention and moves the development and release instructions into CONTRIBUTING.md. --- CONTRIBUTING.md | 69 ++++++++++++++++++++++++++++++++++++++++++++ README.md | 76 +++++++------------------------------------------ 2 files changed, 80 insertions(+), 65 deletions(-) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..ce60f43 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,69 @@ +# Contributing to Gitify GNOME Shell extension + +Thanks for your interest in contributing to the Gitify GNOME Shell extension! + +This repository holds the GNOME Shell extension only. See the [README](README.md) +for what it does and how to install it, and [Gitify][gitify-repo] for the app +itself. + +## Development + +Tooling is unified through [Vite+](https://vite.plus) (oxlint and oxfmt), the +same setup as the main Gitify repository. + +```shell +pnpm install + +# Lint and format checks +pnpm check + +# Auto-fix formatting and lint issues +pnpm check:fix + +# Placement and lifecycle regression tests +pnpm test + +# Real GNOME Wayland smoke test, with GNOME Shell and PyGObject installed +pnpm test:shell + +# Build dist/gitify@gitify.io.shell-extension.zip +pnpm bundle +``` + +The extension itself can only run inside GNOME Shell. To try a change without +logging out, install it into your user extensions directory and start a nested +shell: + +```shell +ln -s "$PWD/gitify@gitify.io" ~/.local/share/gnome-shell/extensions/gitify@gitify.io +dbus-run-session -- gnome-shell --devkit --wayland +``` + +GNOME 45–48 use `--nested` instead of `--devkit`. GNOME 49 and newer may +require the `mutter-devkit` package. See the +[GNOME debugging guide](https://gjs.guide/extensions/development/debugging.html). + +See [desktop validation](docs/testing.md) for the isolated compositor test, +Gitify tray test, and VM checks before release. + +Then enable it inside the nested session and launch Gitify from a terminal in +that session. Shell logs, including anything the extension prints, are +available with: + +```shell +journalctl -f -o cat /usr/bin/gnome-shell +``` + +## Releasing + +Releases are cut by [release-please](https://github.com/googleapis/release-please) +from conventional commits on `main`. Merging the release PR tags the repo, +updates `CHANGELOG.md` and the `version-name` in `metadata.json`, and attaches +the packed `.shell-extension.zip` to the GitHub release. + +Publishing to extensions.gnome.org is a manual step: upload the zip from the +release at . The site assigns the integer +`version` in `metadata.json` itself, so that field is omitted here. + + +[gitify-repo]: https://github.com/gitify-app/gitify diff --git a/README.md b/README.md index d474930..e137534 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# Gitify GNOME Shell extension +# 🐾 Gitify GNOME Shell extension Anchors the [Gitify](https://gitify.io) window to its tray icon on GNOME. @@ -12,7 +12,7 @@ This extension listens for the Gitify window being mapped and moves it directly below the Gitify tray icon, falling back to the top-right corner of the primary monitor when the icon cannot be located. -## Requirements +## 📋 Requirements - GNOME Shell 50 or 51 on a Wayland session. - Gitify 7.8 or newer. @@ -24,21 +24,21 @@ monitor when the icon cannot be located. On an X11 session, or when Gitify's **Use X11 backend** setting is enabled, Gitify positions its own window and this extension is not needed. -## Install +## 🚀 Install After installing the extension, open its settings in GNOME Extensions or Extension Manager for **Set up Gitify**. The page links to the Gitify download and AppIndicator setup, and can open Gitify when a desktop installation is detected. Portable AppImages may need to be opened from your files. -### From extensions.gnome.org +### 🌐 From extensions.gnome.org [Gitify on GNOME Extensions](https://extensions.gnome.org/extension/10968/gitify/) provides version 0.1.0 for GNOME Shell 50. For GNOME Shell 51, use a release bundle whose metadata includes Shell 51 until that version is published on extensions.gnome.org. -### From a release bundle +### 🎁 From a release bundle Download `gitify@gitify.io.shell-extension.zip` from the [latest release](https://github.com/gitify-app/gnome/releases/latest), then: @@ -58,7 +58,7 @@ Gitify 7.8.0 users should enable **Use white tray icon** in Tray settings for the default dark GNOME panel. The automatic white-icon fix is in [gitify#3297](https://github.com/gitify-app/gitify/pull/3297). -## How it works +## 🔧 How it works `extension.js` connects to the window manager's `map` signal. When the mapped window belongs to Gitify (its app id contains `gitify`, or it is a development @@ -74,71 +74,17 @@ on each panel entry. That is a private field of a third-party extension, so it is accessed defensively; if it goes away the extension degrades to corner placement rather than failing. -## Development +## 🤝 Contributing -Tooling is unified through [Vite+](https://vite.plus) (oxlint and oxfmt), the -same setup as the main Gitify repository. +See [CONTRIBUTING.md](CONTRIBUTING.md) for development, testing, and +release instructions. -```shell -pnpm install - -# Lint and format checks -pnpm check - -# Auto-fix formatting and lint issues -pnpm check:fix - -# Placement and lifecycle regression tests -pnpm test - -# Real GNOME Wayland smoke test, with GNOME Shell and PyGObject installed -pnpm test:shell - -# Build dist/gitify@gitify.io.shell-extension.zip -pnpm bundle -``` - -The extension itself can only run inside GNOME Shell. To try a change without -logging out, install it into your user extensions directory and start a nested -shell: - -```shell -ln -s "$PWD/gitify@gitify.io" ~/.local/share/gnome-shell/extensions/gitify@gitify.io -dbus-run-session -- gnome-shell --devkit --wayland -``` - -GNOME 45–48 use `--nested` instead of `--devkit`. GNOME 49 and newer may -require the `mutter-devkit` package. See the -[GNOME debugging guide](https://gjs.guide/extensions/development/debugging.html). - -See [desktop validation](docs/testing.md) for the isolated compositor test, -Gitify tray test, and VM checks before release. - -Then enable it inside the nested session and launch Gitify from a terminal in -that session. Shell logs, including anything the extension prints, are -available with: - -```shell -journalctl -f -o cat /usr/bin/gnome-shell -``` - -## Releasing - -Releases are cut by [release-please](https://github.com/googleapis/release-please) -from conventional commits on `main`. Merging the release PR tags the repo, -updates `CHANGELOG.md` and the `version-name` in `metadata.json`, and attaches -the packed `.shell-extension.zip` to the GitHub release. - -Publishing to extensions.gnome.org is a manual step: upload the zip from the -release at . The site assigns the integer -`version` in `metadata.json` itself, so that field is omitted here. - -## Credits +## 👏 Credits The original extension was written by [@SiriusCrain](https://github.com/SiriusCrain) in [gitify-app/gitify#3297](https://github.com/gitify-app/gitify/pull/3297) and moved here so it can be reviewed and distributed through extensions.gnome.org. -## License +## 📄 License [MIT](LICENSE) From 6b5319031af394a519b90f8684e8e1fa26e940c2 Mon Sep 17 00:00:00 2001 From: Adam Setch Date: Wed, 14 Oct 2026 07:49:44 -0400 Subject: [PATCH 2/5] docs: use the organization profile's brand emoji in the README title --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index e137534..809886a 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# 🐾 Gitify GNOME Shell extension +# 🐧 Gitify GNOME Shell extension Anchors the [Gitify](https://gitify.io) window to its tray icon on GNOME. From f83f8ef9478c394367d19943177cb38afca41c41 Mon Sep 17 00:00:00 2001 From: Adam Setch Date: Wed, 14 Oct 2026 08:02:06 -0400 Subject: [PATCH 3/5] docs: keep the title plain and emoji every section heading Applies the revised heading convention: `#` stays plain, `##` and below carry one emoji. --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 809886a..058e1cd 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# 🐧 Gitify GNOME Shell extension +# Gitify GNOME Shell extension Anchors the [Gitify](https://gitify.io) window to its tray icon on GNOME. From 04e87e120c6be96a447041ce9e89740dae8e40ea Mon Sep 17 00:00:00 2001 From: Adam Setch Date: Wed, 14 Oct 2026 08:02:09 -0400 Subject: [PATCH 4/5] docs: keep the title plain and emoji every section heading Applies the revised heading convention: `#` stays plain, `##` and below carry one emoji. --- CONTRIBUTING.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ce60f43..37f373e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -6,7 +6,7 @@ This repository holds the GNOME Shell extension only. See the [README](README.md for what it does and how to install it, and [Gitify][gitify-repo] for the app itself. -## Development +## 🛠️ Development Tooling is unified through [Vite+](https://vite.plus) (oxlint and oxfmt), the same setup as the main Gitify repository. @@ -54,7 +54,7 @@ available with: journalctl -f -o cat /usr/bin/gnome-shell ``` -## Releasing +## 🚢 Releasing Releases are cut by [release-please](https://github.com/googleapis/release-please) from conventional commits on `main`. Merging the release PR tags the repo, From ecf3062435041fadee6170b3fcbca0969585981b Mon Sep 17 00:00:00 2001 From: Adam Setch Date: Wed, 14 Oct 2026 08:13:43 -0400 Subject: [PATCH 5/5] docs: apply oxfmt formatting to the contributing guide --- CONTRIBUTING.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 37f373e..c775e43 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -66,4 +66,5 @@ release at . The site assigns the integer `version` in `metadata.json` itself, so that field is omitted here. + [gitify-repo]: https://github.com/gitify-app/gitify