Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
3 changes: 2 additions & 1 deletion .prettierrc
Original file line number Diff line number Diff line change
Expand Up @@ -3,5 +3,6 @@
"tabWidth": 2,
"trailingComma": "all",
"semi": true,
"printWidth": 100
"printWidth": 100,
"proseWrap": "never"
}
130 changes: 33 additions & 97 deletions AGENTS.md

Large diffs are not rendered by default.

47 changes: 12 additions & 35 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -1,14 +1,10 @@
# Contributing to Aurora Shell

Understand every change you submit. Keep pull requests focused and include results reviewers can
reproduce.
Understand every change you submit. Keep pull requests focused and include results reviewers can reproduce.

## Start with an issue and branch

Search existing issues and pull requests before opening a duplicate. For a behavior change, describe
the current result, expected result, GNOME Shell version, and reproduction steps. Small documentation
or obvious fixes may go directly to a pull request; discuss broad UI, architecture, settings, or
compatibility changes before implementation.
Search existing issues and pull requests before opening a duplicate. For a behavior change, describe the current result, expected result, GNOME Shell version, and reproduction steps. Small documentation or obvious fixes may go directly to a pull request; discuss broad UI, architecture, settings, or compatibility changes before implementation.

Branch from current `main`:

Expand All @@ -18,18 +14,13 @@ git pull --ff-only
git switch -c fix/short-description
```

Keep one feature, fix, or refactor per pull request. Bug fixes target `main`; released branches
receive separate backport pull requests through the process in
[Releases and backports](docs/releases.md#backports).
Keep one feature, fix, or refactor per pull request. Bug fixes target `main`; released branches receive separate backport pull requests through the process in [Releases and backports](docs/releases.md#backports).

## Make the change

Read [Architecture](docs/architecture.md) before changing lifecycle, metadata, preferences, device
policy, or package boundaries. Use the [module guide](docs/modules.md) for module work.
Read [Architecture](docs/architecture.md) before changing lifecycle, metadata, preferences, device policy, or package boundaries. Use the [module guide](docs/modules.md) for module work.

Add a regression check that fails without a non-trivial fix. Prefer a Node unit test for pure logic
and a targeted Shell test for GNOME behavior. Do not add speculative abstractions, dependencies, or
tests unrelated to the changed contract.
Add a regression check that fails without a non-trivial fix. Prefer a Node unit test for pure logic and a targeted Shell test for GNOME behavior. Do not add speculative abstractions, dependencies, or tests unrelated to the changed contract.

## Choose validation

Expand All @@ -40,14 +31,9 @@ just validate
just test unit
```

Add `just package check` for build/package changes, a targeted `just test shell …` for Shell behavior,
and `just shexli` for EGO-facing, clipboard, subprocess, or package-content changes. Use Toolbox when
the host lacks the project GNOME environment or the change crosses Shell infrastructure.
Add `just package check` for build/package changes, a targeted `just test shell …` for Shell behavior, and `just shexli` for EGO-facing, clipboard, subprocess, or package-content changes. Use Toolbox when the host lacks the project GNOME environment or the change crosses Shell infrastructure.

Record commands and results in the pull request. For user-visible behavior, include a focused
screenshot or screen recording when it proves the result better than logs. For a bug, include the
before/after reproduction. Do not claim a check you did not run; state environment blockers and the
exact error.
Record commands and results in the pull request. For user-visible behavior, include a focused screenshot or screen recording when it proves the result better than logs. For a bug, include the before/after reproduction. Do not claim a check you did not run; state environment blockers and the exact error.

## Commits

Expand All @@ -57,9 +43,7 @@ Use [Conventional Commits](https://www.conventionalcommits.org/) for the subject
<type>[optional scope][!]: <imperative description>
```

Use a standard type such as `feat`, `fix`, `docs`, `refactor`, `test`, `build`, `ci`, or `chore`.
Keep the whole subject under 72 characters, omit the trailing period, and keep each commit reviewable
and revertible. Explain motivation and non-obvious tradeoffs in the body, not a summary of the diff.
Use a standard type such as `feat`, `fix`, `docs`, `refactor`, `test`, `build`, `ci`, or `chore`. Keep the whole subject under 72 characters, omit the trailing period, and keep each commit reviewable and revertible. Explain motivation and non-obvious tradeoffs in the body, not a summary of the diff.

```text
fix(clipboard): preserve card focus behavior
Expand All @@ -68,8 +52,7 @@ Reveal card actions when hover leaves a pinned item and keep short cards at a
stable height. Add Shell coverage for both cases.
```

Mark an incompatible contract with `!` and a `BREAKING CHANGE:` footer. Do not rewrite public release
tags or hide a breaking settings change in a normal fix.
Mark an incompatible contract with `!` and a `BREAKING CHANGE:` footer. Do not rewrite public release tags or hide a breaking settings change in a normal fix.

## Pull requests

Expand All @@ -80,19 +63,13 @@ A pull request should answer four questions:
3. What compatibility, teardown, privacy, or regression risk remains?
4. Which commands and manual artifacts demonstrate the result?

Keep the branch current, respond to review with code or evidence, and wait for the CI gate. Reviewers
may ask for a smaller change when unrelated work obscures the behavior under review.
Keep the branch current, respond to review with code or evidence, and wait for the CI gate. Reviewers may ask for a smaller change when unrelated work obscures the behavior under review.

## AI-assisted contributions

AI tools may assist, but the human contributor owns every line and claim. Review generated changes
against the local GNOME Shell version and the
[GNOME Extensions review guidelines](https://gjs.guide/extensions/review-guidelines/review-guidelines.html).
Remove imaginary APIs, redundant code, prompt-like comments, and claims without test evidence.
AI tools may assist, but the human contributor owns every line and claim. Review generated changes against the local GNOME Shell version and the [GNOME Extensions review guidelines](https://gjs.guide/extensions/review-guidelines/review-guidelines.html). Remove imaginary APIs, redundant code, prompt-like comments, and claims without test evidence.

You must be able to explain the control flow, resource ownership, failure behavior, and test choice.
Disclose material AI assistance when project or employer policy requires it. Never upload secrets,
private user data, or code you are not authorized to share to an external service.
You must be able to explain the control flow, resource ownership, failure behavior, and test choice. Disclose material AI assistance when project or employer policy requires it. Never upload secrets, private user data, or code you are not authorized to share to an external service.

## Documentation map

Expand Down
39 changes: 10 additions & 29 deletions CREDITS.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,9 +4,7 @@ Aurora Shell stands on the work of the wider GNOME community. This file records

## Bluetooth-Battery-Meter

The animated Bluetooth icons used by the **Bluetooth Menu** module come from
[**maniacx/Bluetooth-Battery-Meter**](https://github.com/maniacx/Bluetooth-Battery-Meter).
Huge thanks to [@maniacx](https://github.com/maniacx) for the great work.
The animated Bluetooth icons used by the **Bluetooth Menu** module come from [**maniacx/Bluetooth-Battery-Meter**](https://github.com/maniacx/Bluetooth-Battery-Meter). Huge thanks to [@maniacx](https://github.com/maniacx) for the great work.

Icons (`data/icons/hicolor/scalable/actions/`):

Expand All @@ -17,43 +15,26 @@ Icons (`data/icons/hicolor/scalable/actions/`):
- `bbm-bluetooth-disconnecting-animated-symbolic.svg`
- `bbm-bluetooth-disconnecting-1-symbolic.svg` … `bbm-bluetooth-disconnecting-4-symbolic.svg`

These icons remain the work of their original author and are used under the terms of the
Bluetooth-Battery-Meter project's license.
These icons remain the work of their original author and are used under the terms of the Bluetooth-Battery-Meter project's license.

## XWayland Indicator

The **XWayland Indicator** module is inspired by
[**swsnr/gnome-shell-extension-xwayland-indicator**](https://codeberg.org/swsnr/gnome-shell-extension-xwayland-indicator/).
Thanks to [@swsnr](https://codeberg.org/swsnr) for the original idea of surfacing which
windows run under XWayland.
The **XWayland Indicator** module is inspired by [**swsnr/gnome-shell-extension-xwayland-indicator**](https://codeberg.org/swsnr/gnome-shell-extension-xwayland-indicator/). Thanks to [@swsnr](https://codeberg.org/swsnr) for the original idea of surfacing which windows run under XWayland.

## Weather Clock

The **Weather Clock** module is inspired by
[**CleoMenezesJr/weather-oclock**](https://github.com/CleoMenezesJr/weather-oclock).
Thanks to [@CleoMenezesJr](https://github.com/CleoMenezesJr) for the GNOME Weather clock
integration pattern.
The **Weather Clock** module is inspired by [**CleoMenezesJr/weather-oclock**](https://github.com/CleoMenezesJr/weather-oclock). Thanks to [@CleoMenezesJr](https://github.com/CleoMenezesJr) for the GNOME Weather clock integration pattern.

## Meeting Clock
## Calendar Reminders

The **Meeting Clock** module is inspired by
[**danmoz/meetingtime**](https://github.com/danmoz/meetingtime).
Thanks to [@danmoz](https://github.com/danmoz) for the meeting reminder behavior and
calendar-driven workflow.
The **Calendar Reminders** module is inspired by [**danmoz/meetingtime**](https://github.com/danmoz/meetingtime). Thanks to [@danmoz](https://github.com/danmoz) for the meeting reminder behavior and calendar-driven workflow.

Native Evolution reminders use the `reminders-past` approach demonstrated by [**donnybeelo/gnome-extensions-calendar-reminders**](https://github.com/donnybeelo/gnome-extensions-calendar-reminders). Thanks to [@donnybeelo](https://github.com/donnybeelo) for documenting that flow.

## Capture Tools

The annotation workflow in **Capture Tools** is inspired by
[**AlexanderVanhee/gradia-capture**](https://github.com/AlexanderVanhee/gradia-capture), and its
local screenshot OCR workflow is inspired by
[**SamkitJain660/Shotzy**](https://github.com/SamkitJain660/Shotzy). The custom symbolic SVGs under
`data/icons/hicolor/scalable/actions/` are copied from Gradia Capture and redistributed under
GPL-3.0. The toolbar integration, annotation canvas, export, and OCR implementation are otherwise
independent.
The annotation workflow in **Capture Tools** is inspired by [**AlexanderVanhee/gradia-capture**](https://github.com/AlexanderVanhee/gradia-capture), and its local screenshot OCR workflow is inspired by [**SamkitJain660/Shotzy**](https://github.com/SamkitJain660/Shotzy). The custom symbolic SVGs under `data/icons/hicolor/scalable/actions/` are copied from Gradia Capture and redistributed under GPL-3.0. The toolbar integration, annotation canvas, export, and OCR implementation are otherwise independent.

## Dock Motion

The Dock motion recipes and controller behavior are adapted from
[**Orsso/d2d-companion**](https://github.com/Orsso/d2d-companion), version `v0.1.0-beta.1`
(commit `33eef1d2ddc4678c46d015a4a2c276d4177901df`). The adapted source is redistributed
under GPL-2.0-or-later and is combined with Aurora Shell under GPL-3.0-only.
The Dock motion recipes and controller behavior are adapted from [**Orsso/d2d-companion**](https://github.com/Orsso/d2d-companion), version `v0.1.0-beta.1` (commit `33eef1d2ddc4678c46d015a4a2c276d4177901df`). The adapted source is redistributed under GPL-2.0-or-later and is combined with Aurora Shell under GPL-3.0-only.
2 changes: 1 addition & 1 deletion Containerfile
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
ARG FEDORA_VERSION=44
ARG FEDORA_VERSION=45

FROM registry.fedoraproject.org/fedora-toolbox:${FEDORA_VERSION}

Expand Down
51 changes: 15 additions & 36 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,40 +4,30 @@

# Aurora Shell

Aurora Shell is a GNOME Shell 50 extension with 22 optional desktop features in one preferences
window. It runs inside GNOME Shell and supports no other desktop environment.
Aurora Shell brings optional desktop features to GNOME Shell, from dock and panel controls to appearance, window behavior, and clipboard tools. Choose which modules to enable and configure them in one preferences window.

Supported Shell versions are listed in `metadata.json`. Shell internals change between GNOME
releases, so do not force-install Aurora Shell on an unlisted version. Some modules also depend on
services that may be absent: GNOME Weather for Weather Clock, Tesseract for Capture Tools OCR, and
Vela for Vela VPN Quick Settings.
Supported GNOME Shell versions are listed in [metadata.json](metadata.json). Shell internals change between GNOME releases, so do not force-install Aurora Shell on an unlisted version. Some modules also depend on services that may be absent: GNOME Weather for Weather Clock, Tesseract for Capture Tools OCR, and Vela for Vela VPN Quick Settings.

Aurora Shell is licensed under GPL-3.0-only. See [LICENSE](LICENSE) and [CREDITS.md](CREDITS.md).

## Install

The recommended build is published on
[extensions.gnome.org](https://extensions.gnome.org/extension/9389/aurora-shell/).
The recommended build is published on [extensions.gnome.org](https://extensions.gnome.org/extension/9389/aurora-shell/).

To install a release asset manually, download
`aurora-shell@luminusos.github.io.shell-extension.zip` from the
[GitHub releases page](https://github.com/luminusOS/aurora-shell/releases), then run:
To install a release asset manually, download `aurora-shell@luminusos.github.io.shell-extension.zip` from the [GitHub releases page](https://github.com/luminusOS/aurora-shell/releases), then run:

```bash
gnome-extensions install --force aurora-shell@luminusos.github.io.shell-extension.zip
gnome-extensions enable aurora-shell@luminusos.github.io
```

Log out and back in if the extension is not available in the current Shell session. Open the
Extensions app or run `gnome-extensions prefs aurora-shell@luminusos.github.io` to configure modules.
Log out and back in if the extension is not available in the current Shell session. Open the Extensions app or run `gnome-extensions prefs aurora-shell@luminusos.github.io` to configure modules.

Release assets also include a `.development.shell-extension.zip` package with contributor tools for
development and QA sessions.
Release assets also include a `.development.shell-extension.zip` package with contributor tools for development and QA sessions.

## Update or remove

Install a newer ZIP with the same `--force` command. Existing GSettings values remain in the
extension schema unless you reset them explicitly.
Install a newer ZIP with the same `--force` command. Existing GSettings values remain in the extension schema unless you reset them explicitly.

Disable or remove Aurora Shell with:

Expand All @@ -50,28 +40,20 @@ See [Troubleshooting](docs/troubleshooting.md) when installation, loading, or a

## Modules

All modules can be toggled independently. Most are enabled by default; Auto Theme Switcher and Vela
VPN Quick Settings are opt-in.
All modules can be toggled independently. Most are enabled by default; Auto Theme Switcher and Vela VPN Quick Settings are opt-in.

- **Dock and panel:** Dock, Aurora Menu, Power Menu Avatar, Volume Mixer, Low Battery Percentage,
Lock Key Indicators, Bluetooth Menu, Weather Clock, Meeting Clock, and Tray Icons.
- **Dock and panel:** Dock, Aurora Menu, Power Menu Avatar, Volume Mixer, Low Battery Percentage, Lock Key Indicators, Bluetooth Menu, Weather Clock, Calendar Reminders, and Tray Icons.
- **Appearance:** Theme Changer, Icon Weave, App Search Tooltip, and Auto Theme Switcher.
- **Behavior:** Skip Overview on Login, Pip On Top, Focus Launched Windows, Capture Tools, XWayland
Indicator, and Vela VPN Quick Settings.
- **Behavior:** Skip Overview on Login, Pip On Top, Focus Launched Windows, Capture Tools, XWayland Indicator, and Vela VPN Quick Settings.
- **Privacy and clipboard:** Privacy and Clipboard History.

Low Battery Percentage temporarily enables GNOME's native percentage display while a battery is
discharging below 30%. It does not override a percentage display that the user enabled. Vela VPN
Quick Settings routes the Shell VPN toggle through Vela's D-Bus API; its optional GNOME Shell
fallback is also disabled by default.
Low Battery Percentage temporarily enables GNOME's native percentage display while a battery is discharging below 30%. It does not override a percentage display that the user enabled. Vela VPN Quick Settings routes the Shell VPN toggle through Vela's D-Bus API; its optional GNOME Shell fallback is also disabled by default.

The [module reference](docs/module-reference.md) records every module key, default, dependency,
runtime policy, and implementation/test location.
The [module reference](docs/module-reference.md) records every module key, default, dependency, runtime policy, and implementation/test location.

## Develop

Development requires Node.js 20 or newer, Yarn 4, `just`, and the GNOME 50 development/runtime tools
used by the selected test path.
Follow the [development guide](docs/development.md) to set up the required tools and choose a test environment. The Yarn version is pinned in [package.json](package.json), and [Containerfile](Containerfile) defines the GNOME development environment used by CI and Toolbox. Project commands use `just`.

```bash
just deps
Expand All @@ -80,11 +62,8 @@ just test unit
just package check
```

Start with the [documentation index](docs/README.md). It links to architecture, the edit-run-debug
loop, module authoring, test selection, troubleshooting, and releases. Contributions follow
[CONTRIBUTING.md](CONTRIBUTING.md).
Start with the [documentation index](docs/README.md). It links to architecture, the edit-run-debug loop, module authoring, test selection, troubleshooting, and releases. Contributions follow [CONTRIBUTING.md](CONTRIBUTING.md).

## Credits

Aurora Shell incorporates or adapts work from the GNOME extension community. The complete source,
license, and inspiration record is in [CREDITS.md](CREDITS.md).
Aurora Shell incorporates or adapts work from the GNOME extension community. The complete source, license, and inspiration record is in [CREDITS.md](CREDITS.md).
Loading