Skip to content

Commit 089aa68

Browse files
m1ngsamam1ngsama
authored
Add project documentation (#4)
1 parent 254c779 commit 089aa68

7 files changed

Lines changed: 238 additions & 0 deletions

File tree

‎.github/ISSUE_TEMPLATE/bug_report.md‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
---
2+
name: Bug report
3+
about: Report a problem with Deckless on your Linux desktop
4+
title: "[Bug] "
5+
labels: bug
6+
assignees: ""
7+
---
8+
9+
## Summary
10+
11+
Describe the problem clearly.
12+
13+
## Environment
14+
15+
- Distribution:
16+
- Desktop environment or window manager:
17+
- Display server: X11 or Wayland
18+
- Steam package source:
19+
- `gamescope` installed:
20+
- `gamemode` installed:
21+
22+
## What happened
23+
24+
Describe the observed behavior.
25+
26+
## What you expected
27+
28+
Describe the expected behavior.
29+
30+
## Reproduction steps
31+
32+
1.
33+
2.
34+
3.
35+
36+
## Relevant configuration
37+
38+
Share any relevant `deckless.env` or proxy configuration with secrets removed.
39+
40+
## Extra notes
41+
42+
Add logs, screenshots, or extra context here.

‎.github/ISSUE_TEMPLATE/feature_request.md‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
---
2+
name: Feature request
3+
about: Suggest an improvement for Deckless
4+
title: "[Feature] "
5+
labels: enhancement
6+
assignees: ""
7+
---
8+
9+
## Summary
10+
11+
Describe the workflow or feature you want.
12+
13+
## Problem
14+
15+
What user problem does this solve?
16+
17+
## Proposed direction
18+
19+
Describe the approach you have in mind, if any.
20+
21+
## Alternatives considered
22+
23+
List any alternatives or workarounds you tried.
24+
25+
## Extra notes
26+
27+
Add compatibility notes, links, or examples here.

‎.github/pull_request_template.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
## Summary
2+
3+
- describe the user-facing change
4+
5+
## Testing
6+
7+
- `bash -n install.sh uninstall.sh bin/deckless-steam bin/deckless-bigpicture bin/deckless-i3-bigpicture-bridge`
8+
- `shellcheck install.sh uninstall.sh bin/deckless-steam bin/deckless-bigpicture bin/deckless-i3-bigpicture-bridge`
9+
10+
## Notes
11+
12+
- mention any rollback, compatibility, or documentation impact

‎CHANGELOG.md‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Changelog
2+
3+
All notable changes to this project will be documented in this file.
4+
5+
The format is inspired by Keep a Changelog, and the project follows semantic versioning once tagged releases begin.
6+
7+
## [0.1.0] - 2026-03-28
8+
9+
### Added
10+
11+
- A user-space Steam launcher that preserves the official client while splitting proxy policy between Steam web content and game traffic.
12+
- A runtime-managed `steamwebhelper` wrapper that removes forced GPU disable flags and restores the original Steam wrapper after exit.
13+
- Optional Big Picture launch integration for `gamescope`, `gamemode`, and `mangoapp`.
14+
- An i3 Big Picture bridge that hands fullscreen to launched games and restores it when they exit.
15+
- XDG-friendly install and uninstall scripts.
16+
- Example proxy and runtime configuration files.
17+
- Architecture and i3 integration documentation.
18+
- GitHub Actions validation for shell syntax and ShellCheck.
19+
20+
[0.1.0]: https://github.com/m1ngsama/deckless/releases/tag/v0.1.0

‎CONTRIBUTING.md‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
# Contributing
2+
3+
Thanks for contributing to Deckless.
4+
5+
## Project scope
6+
7+
Deckless exists to improve the real desktop Linux Steam experience without forking or replacing the official Steam package.
8+
9+
Changes are a good fit when they:
10+
11+
- keep the official Steam client as the source of truth
12+
- stay auditable and small
13+
- solve real Linux desktop friction around Steam, Big Picture, controllers, graphics, audio, or proxy policy
14+
- improve installation, rollback, and documentation
15+
16+
Changes are a poor fit when they:
17+
18+
- require patching `/usr/bin/steam`
19+
- permanently rewrite Steam runtime files at rest
20+
- add large background services for problems that can be solved with small scripts
21+
22+
## Development setup
23+
24+
Required local tools:
25+
26+
- `bash`
27+
- `jq`
28+
- `shellcheck`
29+
30+
Optional for runtime testing:
31+
32+
- `steam`
33+
- `gamescope`
34+
- `gamemode`
35+
- `i3`
36+
37+
## Before opening a pull request
38+
39+
Run:
40+
41+
```bash
42+
bash -n install.sh uninstall.sh bin/deckless-steam bin/deckless-bigpicture bin/deckless-i3-bigpicture-bridge
43+
shellcheck install.sh uninstall.sh bin/deckless-steam bin/deckless-bigpicture bin/deckless-i3-bigpicture-bridge
44+
```
45+
46+
If your change affects runtime behavior, include a short note about how you tested it.
47+
48+
## Pull request guidelines
49+
50+
- Keep pull requests focused.
51+
- Explain the user problem first, then the implementation.
52+
- Mention rollback or compatibility impact when you change install behavior.
53+
- Update documentation when you add or rename config variables.
54+
- Add a changelog entry only when preparing a tagged release.
55+
56+
## Issues
57+
58+
Please use the issue templates when possible:
59+
60+
- bug reports for regressions or environment-specific failures
61+
- feature requests for new workflows or platform support
62+
63+
## Code style
64+
65+
- Prefer POSIX-adjacent shell where practical, but Bash is allowed.
66+
- Keep comments short and only where the behavior is not obvious.
67+
- Favor straightforward scripts over clever compactness.

‎README.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -136,6 +136,9 @@ Other X11 desktop environments may still benefit from the proxy split and Big Pi
136136

137137
- [Architecture notes](docs/architecture.md)
138138
- [i3 integration](docs/i3.md)
139+
- [Troubleshooting](docs/troubleshooting.md)
140+
- [Contributing](CONTRIBUTING.md)
141+
- [Changelog](CHANGELOG.md)
139142

140143
## License
141144

‎docs/troubleshooting.md‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
# Troubleshooting
2+
3+
## Steam web pages still do not load
4+
5+
Check the proxy file Deckless is reading:
6+
7+
1. `DECKLESS_PROXY_ENV`
8+
2. `~/.config/deckless/proxy-env.sh`
9+
3. `~/.config/network/proxy-env.sh`
10+
4. inherited shell proxy variables
11+
12+
Things to verify:
13+
14+
- the proxy URL includes a scheme such as `http://` or `socks5h://`
15+
- local addresses are included in `no_proxy`
16+
- the proxy itself is reachable outside Steam
17+
18+
## Games are using the proxy when they should be direct
19+
20+
Deckless clears standard proxy environment variables before starting Steam. If a game still uses a proxy, the most likely causes are:
21+
22+
- the game has its own proxy setting
23+
- a system-wide transparent proxy is in place
24+
- another launcher is injecting environment variables after Deckless starts Steam
25+
26+
## Big Picture still falls back to software rendering
27+
28+
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.
29+
30+
Useful checks:
31+
32+
- `command -v gamescope`
33+
- `glxinfo -B`
34+
- `vulkaninfo --summary`
35+
36+
Also check whether your system exposes one of these paths:
37+
38+
- `/run/host/usr/lib/gbm`
39+
- `/usr/lib/gbm`
40+
- `/run/host/usr/share/glvnd/egl_vendor.d`
41+
- `/usr/share/glvnd/egl_vendor.d`
42+
43+
## Big Picture launches but the game does not take fullscreen on i3
44+
45+
The i3 bridge depends on:
46+
47+
- `i3-msg`
48+
- `jq`
49+
- an i3 session that processes XDG autostart entries, or a manual bridge start
50+
51+
You can start it manually with:
52+
53+
```bash
54+
/usr/bin/bash ~/.local/share/deckless/bin/deckless-i3-bigpicture-bridge
55+
```
56+
57+
If the game first opens a launcher window, that launcher may briefly take the fullscreen seat before the actual game window appears.
58+
59+
## I want to go back to plain Steam
60+
61+
Run:
62+
63+
```bash
64+
./uninstall.sh
65+
```
66+
67+
Deckless restores previously backed up local launchers and desktop entries when they existed at first install.

0 commit comments

Comments
 (0)