From 089aa68172643c5a26513adff21bd1a4440fb46d Mon Sep 17 00:00:00 2001 From: m1ngsama Date: Sat, 28 Mar 2026 18:07:31 +0800 Subject: [PATCH] Add project documentation (#4) --- .github/ISSUE_TEMPLATE/bug_report.md | 42 ++++++++++++++ .github/ISSUE_TEMPLATE/feature_request.md | 27 +++++++++ .github/pull_request_template.md | 12 ++++ CHANGELOG.md | 20 +++++++ CONTRIBUTING.md | 67 +++++++++++++++++++++++ README.md | 3 + docs/troubleshooting.md | 67 +++++++++++++++++++++++ 7 files changed, 238 insertions(+) create mode 100644 .github/ISSUE_TEMPLATE/bug_report.md create mode 100644 .github/ISSUE_TEMPLATE/feature_request.md create mode 100644 .github/pull_request_template.md create mode 100644 CHANGELOG.md create mode 100644 CONTRIBUTING.md create mode 100644 docs/troubleshooting.md diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md new file mode 100644 index 0000000..1969302 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -0,0 +1,42 @@ +--- +name: Bug report +about: Report a problem with Deckless on your Linux desktop +title: "[Bug] " +labels: bug +assignees: "" +--- + +## Summary + +Describe the problem clearly. + +## Environment + +- Distribution: +- Desktop environment or window manager: +- Display server: X11 or Wayland +- Steam package source: +- `gamescope` installed: +- `gamemode` installed: + +## What happened + +Describe the observed behavior. + +## What you expected + +Describe the expected behavior. + +## Reproduction steps + +1. +2. +3. + +## Relevant configuration + +Share any relevant `deckless.env` or proxy configuration with secrets removed. + +## Extra notes + +Add logs, screenshots, or extra context here. diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md new file mode 100644 index 0000000..f704614 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -0,0 +1,27 @@ +--- +name: Feature request +about: Suggest an improvement for Deckless +title: "[Feature] " +labels: enhancement +assignees: "" +--- + +## Summary + +Describe the workflow or feature you want. + +## Problem + +What user problem does this solve? + +## Proposed direction + +Describe the approach you have in mind, if any. + +## Alternatives considered + +List any alternatives or workarounds you tried. + +## Extra notes + +Add compatibility notes, links, or examples here. diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..2088a62 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,12 @@ +## Summary + +- describe the user-facing change + +## Testing + +- `bash -n install.sh uninstall.sh bin/deckless-steam bin/deckless-bigpicture bin/deckless-i3-bigpicture-bridge` +- `shellcheck install.sh uninstall.sh bin/deckless-steam bin/deckless-bigpicture bin/deckless-i3-bigpicture-bridge` + +## Notes + +- mention any rollback, compatibility, or documentation impact diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..6577700 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,20 @@ +# Changelog + +All notable changes to this project will be documented in this file. + +The format is inspired by Keep a Changelog, and the project follows semantic versioning once tagged releases begin. + +## [0.1.0] - 2026-03-28 + +### Added + +- A user-space Steam launcher that preserves the official client while splitting proxy policy between Steam web content and game traffic. +- A runtime-managed `steamwebhelper` wrapper that removes forced GPU disable flags and restores the original Steam wrapper after exit. +- Optional Big Picture launch integration for `gamescope`, `gamemode`, and `mangoapp`. +- An i3 Big Picture bridge that hands fullscreen to launched games and restores it when they exit. +- XDG-friendly install and uninstall scripts. +- Example proxy and runtime configuration files. +- Architecture and i3 integration documentation. +- GitHub Actions validation for shell syntax and ShellCheck. + +[0.1.0]: https://github.com/m1ngsama/deckless/releases/tag/v0.1.0 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..084701b --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,67 @@ +# Contributing + +Thanks for contributing to Deckless. + +## Project scope + +Deckless exists to improve the real desktop Linux Steam experience without forking or replacing the official Steam package. + +Changes are a good fit when they: + +- keep the official Steam client as the source of truth +- stay auditable and small +- solve real Linux desktop friction around Steam, Big Picture, controllers, graphics, audio, or proxy policy +- improve installation, rollback, and documentation + +Changes are a poor fit when they: + +- require patching `/usr/bin/steam` +- permanently rewrite Steam runtime files at rest +- add large background services for problems that can be solved with small scripts + +## Development setup + +Required local tools: + +- `bash` +- `jq` +- `shellcheck` + +Optional for runtime testing: + +- `steam` +- `gamescope` +- `gamemode` +- `i3` + +## Before opening a pull request + +Run: + +```bash +bash -n install.sh uninstall.sh bin/deckless-steam bin/deckless-bigpicture bin/deckless-i3-bigpicture-bridge +shellcheck install.sh uninstall.sh bin/deckless-steam bin/deckless-bigpicture bin/deckless-i3-bigpicture-bridge +``` + +If your change affects runtime behavior, include a short note about how you tested it. + +## Pull request guidelines + +- Keep pull requests focused. +- Explain the user problem first, then the implementation. +- Mention rollback or compatibility impact when you change install behavior. +- Update documentation when you add or rename config variables. +- Add a changelog entry only when preparing a tagged release. + +## Issues + +Please use the issue templates when possible: + +- bug reports for regressions or environment-specific failures +- feature requests for new workflows or platform support + +## Code style + +- Prefer POSIX-adjacent shell where practical, but Bash is allowed. +- Keep comments short and only where the behavior is not obvious. +- Favor straightforward scripts over clever compactness. diff --git a/README.md b/README.md index b94d697..8bf7302 100644 --- a/README.md +++ b/README.md @@ -136,6 +136,9 @@ Other X11 desktop environments may still benefit from the proxy split and Big Pi - [Architecture notes](docs/architecture.md) - [i3 integration](docs/i3.md) +- [Troubleshooting](docs/troubleshooting.md) +- [Contributing](CONTRIBUTING.md) +- [Changelog](CHANGELOG.md) ## License diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md new file mode 100644 index 0000000..c5cfb7a --- /dev/null +++ b/docs/troubleshooting.md @@ -0,0 +1,67 @@ +# Troubleshooting + +## Steam web pages still do not load + +Check the proxy file Deckless is reading: + +1. `DECKLESS_PROXY_ENV` +2. `~/.config/deckless/proxy-env.sh` +3. `~/.config/network/proxy-env.sh` +4. inherited shell proxy variables + +Things to verify: + +- the proxy URL includes a scheme such as `http://` or `socks5h://` +- local addresses are included in `no_proxy` +- the proxy itself is reachable outside Steam + +## Games are using the proxy when they should be direct + +Deckless clears standard proxy environment variables before starting Steam. If a game still uses a proxy, the most likely causes are: + +- the game has its own proxy setting +- a system-wide transparent proxy is in place +- another launcher is injecting environment variables after Deckless starts Steam + +## Big Picture still falls back to software rendering + +Confirm that your system has working graphics userspace outside Steam first. Deckless only removes some Steam-side blockers; it cannot fix a broken driver stack. + +Useful checks: + +- `command -v gamescope` +- `glxinfo -B` +- `vulkaninfo --summary` + +Also check whether your system exposes one of these paths: + +- `/run/host/usr/lib/gbm` +- `/usr/lib/gbm` +- `/run/host/usr/share/glvnd/egl_vendor.d` +- `/usr/share/glvnd/egl_vendor.d` + +## Big Picture launches but the game does not take fullscreen on i3 + +The i3 bridge depends on: + +- `i3-msg` +- `jq` +- an i3 session that processes XDG autostart entries, or a manual bridge start + +You can start it manually with: + +```bash +/usr/bin/bash ~/.local/share/deckless/bin/deckless-i3-bigpicture-bridge +``` + +If the game first opens a launcher window, that launcher may briefly take the fullscreen seat before the actual game window appears. + +## I want to go back to plain Steam + +Run: + +```bash +./uninstall.sh +``` + +Deckless restores previously backed up local launchers and desktop entries when they existed at first install.