Repository: espanso/espanso
Pull request #2297: :memo: Update supported platforms and add the triage methodology
Author: login: AucaCoyan
Created: 2025-04-12T15:05:16Z | Merged: 2025-04-21T21:39:15Z

It's time we do a guide on our supported platforms, and the meaning of high / medium / low priorities

- [x] add links to the epics per platform
- [x] add description to triaging issues

Useful sources I read:
[zig platform support](https://ziglang.org/download/0.8.1/release-notes.html#toc-Support-Table)
[rust platform support](https://github.com/rust-lang/rust/blob/master/src/doc/rustc/src/platform-support.md)


Diff:
diff --git a/README.md b/README.md
index 4a84318cd..7f1ec088f 100644
--- a/README.md
+++ b/README.md
@@ -46,10 +46,10 @@ ___
 
 Visit the [official documentation](https://espanso.org/docs/).
 
-## Support
-
 If you need some help to setup espanso, want to ask a question or simply get involved
-in the community, [Join the official Subreddit](https://www.reddit.com/r/espanso/)! :)
+in the community, you can [join the official Subreddit](https://www.reddit.com/r/espanso/)
+ or [join the official Discord](https://discord.gg/DFcCNDg7bB)!
+
 
 ## Donations
 
diff --git a/SUMMARY.md b/SUMMARY.md
deleted file mode 100644
index 532e18204..000000000
--- a/SUMMARY.md
+++ /dev/null
@@ -1,12 +0,0 @@
-# Summary
-
-- [Introduction](./ch00-introduction.md)
-- [General guidelines](./ch01-general-guidelines.md)
-- [Building and compilation](./ch02-building-and-compilation.md)
-  - [Windows](./ch02-windows.md)
-  - [macOS](./ch02-macos.md)
-  - [linux](./ch02-linux.md)
-- [General documentation](./ch03-general-documentation.md)
-- [Creating a PR](./ch04-creating-a-pr.md)
-- [Dev recipes and cookbook](./ch05-recipes-and-cookbook.md)
-  - [Creating a release](./ch05-01-creating-a-release.md)
diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md
index 783f496b8..a7c84b541 100644
--- a/docs/src/SUMMARY.md
+++ b/docs/src/SUMMARY.md
@@ -1,7 +1,9 @@
 # Summary
 
 - [Introduction](./ch01-introduction.md)
-- [General guidelines](./ch02-general-guidelines.md)
+- [General guidelines](./ch02-00-general-guidelines.md)
+  - [Platform support](./ch02-01-platform-tiers.md)
+  - [Triage method](./ch02-02-triage-method.md)
 - [Building and compilation](./ch03-00-building-and-compilation.md)
   - [Windows](./ch03-01-windows.md)
   - [macOS](./ch03-02-macos.md)
diff --git a/docs/src/ch02-general-guidelines.md b/docs/src/ch02-00-general-guidelines.md
similarity index 100%
rename from docs/src/ch02-general-guidelines.md
rename to docs/src/ch02-00-general-guidelines.md
diff --git a/docs/src/ch02-01-platform-tiers.md b/docs/src/ch02-01-platform-tiers.md
new file mode 100644
index 000000000..758779895
--- /dev/null
+++ b/docs/src/ch02-01-platform-tiers.md
@@ -0,0 +1,42 @@
+# Platform Tiers
+
+We have different tiers to indicate different levels of commitment for each
+architecture + Operative System. In linux, we also have 2 desktop
+implementations, X11 and Wayland.
+
+In the Tier 1, we want to garantee the installation, configuration and general
+usage of the app. This are the platforms we spend the majority of time.
+
+- ✅ CI will always build and pass all the tests
+- ✅ Releases are built for these platforms
+
+Tier 2 is what can we do to our best efforts. This means sometimes we need to
+break compatibility, or we need to stop supporting some features because there
+are fewer users compared to the tier 1.
+
+Tier 3 is unsupported. This is because we don't have hardware to compile or
+reproduce the bugs. The shortage of people certainly doesn't help here. Help
+needed!
+
+### Tier 1: core
+
+- x86_64 Windows 11 (latest)
+- ARM64 (Silicon) macOS Sonoma (latest)
+- x86_64 Ubuntu 24.04 (LTS)
+- x86_64 Debian 12 (stable)
+
+### Tier 2: our best effort
+
+- x86_64 Windows 10 (close to end of service)
+- x86_64 macOS (Intel)
+- x86_64 Debian testing and Debian Sid (unstable)
+- x86_64 Fedora distros
+- x86_64 Arch linux
+- x86_64 nixOS
+
+### Tier 3: unsupported
+
+- FreeBSD and the BSD family ([tracking issue](https://github.com/espanso/espanso/issues/2304))
+- ChromeOS ([tracking issue](https://github.com/espanso/espanso/issues/2305))
+- Windows ARM architectures ([tracking issue](https://github.com/espanso/espanso/issues/2306)).
+- Windows in 32 bits is unsupported.
diff --git a/docs/src/ch02-02-triage-method.md b/docs/src/ch02-02-triage-method.md
new file mode 100644
index 000000000..2e85c55f2
--- /dev/null
+++ b/docs/src/ch02-02-triage-method.md
@@ -0,0 +1,53 @@
+# Triage method
+
+We want to be consistent in the order in which we bring value to our users.
+
+For that we need to have a common ground and method to classify bugs from
+enhancements, define what has high priority and what low priority, and so on.
+
+It makes sense that order of priority follows the normal usage of the app, that
+is the user:
+
+1) Downloads the app, (assuming downloading the correct version for his/her
+platform)
+2) Install the app and there are no errors or warnings
+3) Follows the welcome tutorial and Espanso triggers `Hello there!` correctly
+
+From here there are a couple of approaches, probably:
+
+- the user search how to add triggers and checks the configuration available
+- the user lookup for some packages, finds the hub, and then installs some of
+them.
+
+In addition, some users can clone the repository from GitHub and compile from
+source, if needed. So that's an additional area to cover from the beginning.
+
+> ⚠️ IMPORTANT
+>
+> Any problem compiling, downloading, installing or following the welcome tutorial
+will be categorized as `high priority`. If multiple problems appear, they are
+sorted in the named order.
+
+The statement above is valid under our [supported platforms](./ch02-01-platform-tiers.md),
+ of course.
+
+## So... what's medium or low priority then?
+
+It's a difficult line to trace, but we have to draw it somewhere. Medium priority
+is distinguised when it doesn't have `high` or `low` priority tags, so it's the
+default for the issues.
+
+`low priority` is acceptable for cases where:
+- is an enhancement or feature that is difficult to implement, and we feel it
+has very low impact on our users
+- the above, especially when there is an alternative, non-native solution
+- we don't have the water level up for the task (unsupported platforms, bugs
+very difficult to reproduce, or short of staff)
+- stuff we think is not important for the current state of the app
+
+This doesn't mean the work is stopped on those areas, it's just stalled becase we
+have loads of more important things to do. Note that many issues qualify to be
+low-priority, but we want to solve them sooner than others.
+
+Additionaly, we want to have a consistent value delivery, so we aim to have
+around the same amount of high priority issues any time of the year.
diff --git a/docs/src/ch04-00-general-documentation.md b/docs/src/ch04-00-general-documentation.md
index ea5e8ada0..bded2b04d 100644
--- a/docs/src/ch04-00-general-documentation.md
+++ b/docs/src/ch04-00-general-documentation.md
@@ -6,6 +6,8 @@ chapters will sound a lot untidy.
 ## General great resources to learn
 
 - We use `gdiplus` in some places. [Here is the doc from mslearn](https://learn.microsoft.com/en-us/windows/win32/gdiplus/-gdiplus-gdi-start)
+- Here is the [documentation on wxWidgets 3.1.5](https://docs.wxwidgets.org/3.1.5/),
+the version we use currently in espanso.
 
 ## Cache folder
 


Reviews:
user: login: smeech
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-04-17T00:03:45Z
user: login: AucaCoyan
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-04-17T12:01:16Z

Review comments:
diff_hunk: @@ -0,0 +1,39 @@
+# Platform Tiers
+
+We have different tiers to indicate different levels of commitment for each
+architecture + Operative System.
path: docs/src/ch02-01-platform-tiers.md
user: login: smeech
body: Is it worth mentioning the different levels of implementation between X11 and Wayland desktop environments? 
created_at: 2025-04-17T00:03:37Z
author_association: COLLABORATOR
diff_hunk: @@ -0,0 +1,39 @@
+# Platform Tiers
+
+We have different tiers to indicate different levels of commitment for each
+architecture + Operative System.
path: docs/src/ch02-01-platform-tiers.md
user: login: AucaCoyan
body: Yes! I missed that
created_at: 2025-04-17T12:01:16Z
author_association: COLLABORATOR

PR comments:
user: login: AucaCoyan
created_at: 2025-04-18T18:13:56Z
body: Hey! @smeech @joh6nn @Archigos
I finished the first draft. Can you do a review? 😊 Thanks!
author_association: COLLABORATOR
user: login: joh6nn
created_at: 2025-04-18T21:37:55Z
body: In general this looks good to me, but I'm not sure about completely replacing Reddit with Discord. My preference would be to have both. Reddit has the advantage that questions+answers posted there can be googled; questions we Nsser in Discord are doomed to be asked over and over again because the answers aren't googlable
author_association: COLLABORATOR
user: login: AucaCoyan
created_at: 2025-04-19T15:31:09Z
body: Right! I added the reddit again 😊.

Are all on board? any further comments?
author_association: COLLABORATOR