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. - diff --git a/README.md b/README.md index b80b4e9..4d31973 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 + +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 +### 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](https://github.com/prasannavl/p7-borders-shell-extension) \ No newline at end of file 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