From e529e3b5b7cee3f96920836905be5513d69573d6 Mon Sep 17 00:00:00 2001 From: Alexander Pechmann Date: Thu, 4 Jun 2026 20:29:43 +0200 Subject: [PATCH 1/5] chore: restructured, added Summary and Contributing reference --- README.md | 28 +++++++++++++++++++++++----- 1 file changed, 23 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index b80b4e9..3035bf4 100644 --- a/README.md +++ b/README.md @@ -1,23 +1,35 @@ [![Project Status: Beta](https://img.shields.io/badge/status-beta-orange.svg)](https://github.com/KonstantinMerkel/workflow-tiling) # Workflow Tiling - A deterministic customizable auto-tiler extension for GNOME Shell (GNOME 50+). +## Summary +- [Workflow Tiling](#workflow-tiling) + - [Summary](#summary) + - [Features](#features) + - [Customizations](#customizations) + - [Custom Layouts](#custom-layouts) + - [Development](#development) + - [Contributing](#contributing) + - [Running Tests](#running-tests) + - [Installation](#installation) + - [Recommended Extensions](#recommended-extensions) + ## Features - **Deterministic Escalation**: Automatically tiles windows in a customizable geometric sequence. - **Multi-Monitor Support**: Each monitor tiles independently. - **Workspace Isolation**: Tiling states are unique to each GNOME workspace. - **Stability Focused**: Uses WindowWrapper object modeling and compositor-native synchronization (Meta.LaterType) to prevent race conditions and Shell crashes. -## Recommended Extensions -Workflow Tiling does not natively draw an active window border. For visual indication of the focused window, it is highly recommended to use an extension like **P7 Border** +## Customizations + +ToDo: Reference the `Gnome Extension Manager` > `Workflow Tiling` > Settings +ToDo: Hint/Explain behavior with duplicate shortcuts -## Custom Layouts +### Custom Layouts Layout transitions are configured via JSON string, supporting custom window counts and sizes. Optional `id` (1-indexed) integer properties in the JSON structure define how windows transition between states. It is required for all elements: - ```json { "1": [ @@ -37,6 +49,9 @@ Optional `id` (1-indexed) integer properties in the JSON structure define how wi ## Development +### Contributing +see [CONTRIBUTING.md](CONTRIBUTING.md) + ### Running Tests Unit tests are written using **Vitest**. ```bash @@ -49,3 +64,6 @@ To deploy the extension to your local GNOME Shell directory: ```bash make install ``` + +## Recommended Extensions +Workflow Tiling does not natively draw an active window border. For visual indication of the focused window, it is highly recommended to use an extension like **P7 Border** \ No newline at end of file From d1ba95d82d6f0d70bdc5f63e11280b76600898c5 Mon Sep 17 00:00:00 2001 From: Alexander Pechmann Date: Thu, 4 Jun 2026 20:46:14 +0200 Subject: [PATCH 2/5] chore: added customization description --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 3035bf4..848f4aa 100644 --- a/README.md +++ b/README.md @@ -23,8 +23,8 @@ A deterministic customizable auto-tiler extension for GNOME Shell (GNOME 50+). ## Customizations -ToDo: Reference the `Gnome Extension Manager` > `Workflow Tiling` > Settings -ToDo: Hint/Explain behavior with duplicate shortcuts +Customizations like window gaps and keybinds can be customized under `Gnome Extension Manager` > `Workflow Tiling` > Settings. +Please be warned that duplicate shortcuts can lead to unexpected window movement. ### Custom Layouts Layout transitions are configured via JSON string, supporting custom window counts and sizes. From ccce5a0f112daf8aa6c8247a724a3913b2f107a4 Mon Sep 17 00:00:00 2001 From: MAkexander <86495108+MAkexander@users.noreply.github.com> Date: Thu, 4 Jun 2026 21:06:59 +0200 Subject: [PATCH 3/5] Updated external Plugin Reference Updated reference to be a Markdown link Co-authored-by: Konstantin Merkel --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 848f4aa..4d31973 100644 --- a/README.md +++ b/README.md @@ -66,4 +66,4 @@ make install ``` ## Recommended Extensions -Workflow Tiling does not natively draw an active window border. For visual indication of the focused window, it is highly recommended to use an extension like **P7 Border** \ No newline at end of file +Workflow Tiling does not natively draw an active window border. For visual indication of the focused window, it is highly recommended to use an extension like [P7 Border](https://github.com/prasannavl/p7-borders-shell-extension) \ No newline at end of file From 0555757cdb352f4b5397e9f801f182934e2d8eed Mon Sep 17 00:00:00 2001 From: Alexander Pechmann Date: Thu, 4 Jun 2026 21:25:22 +0200 Subject: [PATCH 4/5] refactor: moved documentation files to doc/ --- architecture.md => docs/architecture.md | 0 layouts.md => docs/layouts.md | 0 vision.md => docs/vision.md | 0 3 files changed, 0 insertions(+), 0 deletions(-) rename architecture.md => docs/architecture.md (100%) rename layouts.md => docs/layouts.md (100%) rename vision.md => docs/vision.md (100%) diff --git a/architecture.md b/docs/architecture.md similarity index 100% rename from architecture.md rename to docs/architecture.md diff --git a/layouts.md b/docs/layouts.md similarity index 100% rename from layouts.md rename to docs/layouts.md diff --git a/vision.md b/docs/vision.md similarity index 100% rename from vision.md rename to docs/vision.md From 789d8adfdb286ea5da105cc9038c9050f6158cc4 Mon Sep 17 00:00:00 2001 From: Alexander Pechmann Date: Thu, 4 Jun 2026 21:34:07 +0200 Subject: [PATCH 5/5] refactor: Restructured the file to follow the same order as a typical development process and added notes about issues and feature requets --- CONTRIBUTING.md | 44 +++++++++++++++++++++----------------------- 1 file changed, 21 insertions(+), 23 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 994d487..45d9fa6 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,9 +1,7 @@ -# Ground rules on contributing to Workflow Tiling - -Welcome! Thanks for wanting to contribute. If you have any issues reach out to the maintainer. - -## Branching Structure +# Development Guidelines for `Workflow Tiling` +Welcome! Thanks for wanting to contribute. If you have any issues please reach out to the maintainer. +## Branch Structure We follow a structured branching model to keep things organized: * **`master`**: This is our stable, release-ready branch. Please do not push directly here. @@ -11,7 +9,24 @@ We follow a structured branching model to keep things organized: * **`feature/*`, `bugfix/*`, `refactor/*`**: Use these short-lived branches for your daily work. When ready, open a Pull Request into `develop`. * **`hotfix/*`** (Exception): If `master` breaks, you can create a hotfix branch to merge directly into `master`. -## Development Guidelines +## Issues and Feature Requests +Please report issues and request features under issues. + +### AI Friendliness +This project has a project-level `AGENTS.md` set up. +You may have your own requirements in `CLAUDE.md`, `CODEX.md`, `CURSOR.md`, or `GEMINI.md`. +Please make sure to tell your agent to respect both `AGENTS.md` and your local instruction file. + +### Settings UI Design +We love a clean UI! For `prefs.js`, follow a **"minimal clutter, expand only after needed"** design philosophy. +Feel free to use `Adw` (libadwaita) components and bind visibility state dynamically to reduce visual noise. + +### Logging +Using debuggable logging (`Logger` in `lib/logger.js`) is highly suggested. Including verbose logs for complex state sequences makes troubleshooting much easier for everyone — especially me. Thank you! + +### GNOME APIs & Event-Driven Architecture +We aim to use the newest solutions and APIs available for GNOME Shell. +Please rely on GNOME Shell signals (`size-changed`, `window-created`, etc.) or frame-synced deferrals (`GLib.idle_add`, `Meta.LaterType.BEFORE_REDRAW`) instead of arbitrary timeouts (`GLib.timeout_add`). ### Testing We highly value stability! Please make sure to write unit tests for new features—wherever possible—and run existing tests before proposing a change. @@ -24,20 +39,3 @@ npm test We prefer documentation that describes the current state and behavior of the system. * Try to keep comments focused without diary entries or historical tracking. * If your changes affect how the system works (class names, execution flow, or API), please help us keep `architecture.md`, `layouts.md`, and `README.md` up-to-date! - -### Logging -Using debuggable logging (`Logger` in `lib/logger.js`) is highly suggested. Including verbose logs for complex state sequences makes troubleshooting much easier for everyone—especially me. Thanks! - -### Settings UI Design -We love a clean UI! For `prefs.js`, follow a **"minimal clutter, expand only after needed"** design philosophy. -Feel free to use `Adw` (libadwaita) components and bind visibility state dynamically to reduce visual noise. - -### GNOME APIs & Event-Driven Architecture -We aim to use the newest solutions and APIs available for GNOME Shell. -Please rely on GNOME Shell signals (`size-changed`, `window-created`, etc.) or frame-synced deferrals (`GLib.idle_add`, `Meta.LaterType.BEFORE_REDRAW`) instead of arbitrary timeouts (`GLib.timeout_add`). - -### AI Friendliness -This project has a project-level `AGENTS.md` set up. -You may have your own requirements in `CLAUDE.md`, `CODEX.md`, `CURSOR.md`, or `GEMINI.md`. -Please make sure to tell your agent to respect both `AGENTS.md` and your local instruction file. -