Skip to content

docs: add emoji headings and a contributing guide #43

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
setchy merged 5 commits into from
Oct 14, 2026
Merged

docs: add emoji headings and a contributing guide #43

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
2e7f256
docs: add emoji headings and a contributing guide
setchy Oct 14, 2026
6b53190
docs: use the organization profile's brand emoji in the README title
setchy Oct 14, 2026
f83f8ef
docs: keep the title plain and emoji every section heading
setchy Oct 14, 2026
04e87e1
docs: keep the title plain and emoji every section heading
setchy Oct 14, 2026
ecf3062
docs: apply oxfmt formatting to the contributing guide
setchy Oct 14, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
70 changes: 70 additions & 0 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,70 @@
# 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 <https://extensions.gnome.org/upload/>. The site assigns the integer
`version` in `metadata.json` itself, so that field is omitted here.

<!-- LINK LABELS -->

[gitify-repo]: https://github.com/gitify-app/gitify
74 changes: 10 additions & 64 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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:
Expand All @@ -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
Expand All @@ -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 <https://extensions.gnome.org/upload/>. 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)
Loading