Skip to content

Commit 9c2c0b6

Browse files
mk-fridaymk-friday
committed
docs: add contributor and release templates
1 parent 2854f9e commit 9c2c0b6

7 files changed

Lines changed: 317 additions & 0 deletions

File tree

‎.github/ISSUE_TEMPLATE/bug_report.yml‎

Lines changed: 99 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
1+
name: Bug report
2+
description: Report a problem with tailscale-tray
3+
labels:
4+
- bug
5+
body:
6+
- type: markdown
7+
attributes:
8+
value: |
9+
Thanks for reporting this. Please include enough detail to reproduce the problem, especially your desktop environment, install method, and how Tailscale is installed.
10+
11+
- type: input
12+
id: version
13+
attributes:
14+
label: App version
15+
description: What version of tailscale-tray are you running?
16+
placeholder: 0.1.0
17+
validations:
18+
required: true
19+
20+
- type: input
21+
id: distro
22+
attributes:
23+
label: Linux distro and version
24+
placeholder: Fedora 42 KDE
25+
validations:
26+
required: true
27+
28+
- type: input
29+
id: desktop
30+
attributes:
31+
label: Desktop environment
32+
placeholder: KDE Plasma 6
33+
validations:
34+
required: true
35+
36+
- type: dropdown
37+
id: install_method
38+
attributes:
39+
label: How did you install tailscale-tray?
40+
options:
41+
- RPM from GitHub Releases
42+
- Built from source
43+
- Running from source without installing
44+
- Other
45+
validations:
46+
required: true
47+
48+
- type: dropdown
49+
id: tailscale_install
50+
attributes:
51+
label: How is Tailscale installed?
52+
options:
53+
- Fedora/RPM package
54+
- Snap
55+
- Manual binary install
56+
- Other
57+
validations:
58+
required: true
59+
60+
- type: textarea
61+
id: bug
62+
attributes:
63+
label: What happened?
64+
description: Describe the bug clearly.
65+
placeholder: Clicking Open Tailscale Admin does nothing.
66+
validations:
67+
required: true
68+
69+
- type: textarea
70+
id: expected
71+
attributes:
72+
label: What did you expect to happen?
73+
validations:
74+
required: true
75+
76+
- type: textarea
77+
id: reproduce
78+
attributes:
79+
label: Steps to reproduce
80+
placeholder: |
81+
1. Launch tailscale-tray
82+
2. Open tray menu
83+
3. Click Open Tailscale Admin
84+
4. Nothing happens
85+
validations:
86+
required: true
87+
88+
- type: textarea
89+
id: diagnostics
90+
attributes:
91+
label: Diagnostics / logs
92+
description: Paste relevant output from Show diagnostics, terminal logs, or command output.
93+
render: shell
94+
95+
- type: textarea
96+
id: extra
97+
attributes:
98+
label: Extra context
99+
description: Screenshots, related issues, packaging quirks, or anything else helpful.

‎.github/ISSUE_TEMPLATE/config.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
blank_issues_enabled: false

‎.github/ISSUE_TEMPLATE/feature_request.yml‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
name: Feature request
2+
description: Suggest an improvement for tailscale-tray
3+
labels:
4+
- enhancement
5+
body:
6+
- type: markdown
7+
attributes:
8+
value: |
9+
Thanks for the idea. Please focus on the user problem first, then the proposed solution.
10+
11+
- type: textarea
12+
id: problem
13+
attributes:
14+
label: What problem are you trying to solve?
15+
placeholder: It is hard to tell why Connect failed without opening a terminal.
16+
validations:
17+
required: true
18+
19+
- type: textarea
20+
id: proposal
21+
attributes:
22+
label: What would you like to see?
23+
placeholder: Add a clearer failure dialog that suggests likely causes.
24+
validations:
25+
required: true
26+
27+
- type: textarea
28+
id: alternatives
29+
attributes:
30+
label: Alternatives considered
31+
description: Optional, but helpful if you already tried other approaches.
32+
33+
- type: dropdown
34+
id: area
35+
attributes:
36+
label: What area does this affect?
37+
options:
38+
- Tray UI
39+
- Diagnostics
40+
- Packaging / release
41+
- Install / docs
42+
- Desktop integration
43+
- Tailscale command behavior
44+
- Other
45+
validations:
46+
required: true
47+
48+
- type: textarea
49+
id: extra
50+
attributes:
51+
label: Extra context
52+
description: Mockups, screenshots, related tools, or platform-specific notes.

‎.github/pull_request_template.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
## Summary
2+
3+
- what changed:
4+
- why:
5+
6+
## Testing
7+
8+
- [ ] `make test`
9+
- [ ] tested manually if UI behavior changed
10+
11+
## Notes
12+
13+
- desktop environment tested:
14+
- Tailscale install type tested:
15+
- packaging/docs updated if needed:
16+
17+
## Screenshots
18+
19+
If the visible UI changed, add screenshots or short notes here.

‎CONTRIBUTING.md‎

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
# Contributing
2+
3+
Thanks for helping improve `tailscale-tray`.
4+
5+
## Scope and goals
6+
7+
This project is intentionally small.
8+
9+
Please prefer:
10+
- focused fixes
11+
- small, reviewable pull requests
12+
- targeted UX improvements
13+
- tests for behavior changes when practical
14+
15+
Please avoid unrelated refactors or dependency churn unless there is a clear reason.
16+
17+
## Development setup
18+
19+
### Run tests
20+
21+
```bash
22+
make test
23+
```
24+
25+
### Run from source
26+
27+
```bash
28+
python3 -m pip install --user -r requirements.txt
29+
python3 app.py
30+
```
31+
32+
### Build an RPM in Docker
33+
34+
```bash
35+
make build-rpm-container VERSION=0.1.0
36+
```
37+
38+
## Repo structure
39+
40+
- `app.py` - Qt wiring and tray app entrypoint
41+
- `tray_controller.py` - controller/process lifecycle logic
42+
- `tray_view.py` - pure presentation rules for tray state
43+
- `diagnostics_view.py` - pure diagnostics presenter
44+
- `tailscale_status.py` - parses `tailscale status --json`
45+
- `tailscale_command.py` - interprets command outcomes/failures
46+
- `tailscale_cli.py` - CLI path detection helpers
47+
- `tray_icon.py` - branded icon rendering
48+
- `tests/` - unit tests
49+
- `packaging/` - desktop entry, spec file, Docker builder
50+
- `scripts/` - build helpers
51+
52+
## Contribution guidelines
53+
54+
- Keep changes narrow and purposeful
55+
- Add or update tests when behavior changes
56+
- Preserve headless testability for pure logic where possible
57+
- Prefer pure helpers/presenters/controllers over pushing more logic into Qt widgets
58+
- Keep Linux/KDE-first assumptions explicit in docs
59+
- Do not add a hard runtime dependency on a specific Tailscale package if a working CLI is enough
60+
61+
## Pull requests
62+
63+
Before opening a PR:
64+
- run `make test`
65+
- update README/docs if behavior changed
66+
- mention packaging or desktop-environment assumptions
67+
- include screenshots if the UI changed visibly
68+
69+
Good PRs usually include:
70+
- what changed
71+
- why it changed
72+
- how it was tested
73+
- any limitations or follow-up ideas
74+
75+
## Release/versioning notes
76+
77+
Releases are tag-driven.
78+
79+
Examples:
80+
81+
```bash
82+
git tag v0.1.1
83+
git push origin v0.1.1
84+
```
85+
86+
That triggers the GitHub release workflow and publishes the RPM artifact.
87+
88+
For maintainers, see `RELEASE_CHECKLIST.md`.

‎README.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -242,6 +242,11 @@ You can trigger releases in two ways:
242242

243243
Issues and PRs are welcome.
244244

245+
See:
246+
- `CONTRIBUTING.md`
247+
- `RELEASE_CHECKLIST.md`
248+
- `.github/ISSUE_TEMPLATE/`
249+
245250
Useful commands:
246251

247252
```bash

‎RELEASE_CHECKLIST.md‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
# Release checklist
2+
3+
Use this when cutting a new `tailscale-tray` release.
4+
5+
## Before tagging
6+
7+
- [ ] `make test` passes locally
8+
- [ ] README matches current behavior and packaging flow
9+
- [ ] release workflow files still match the documented versioning approach
10+
- [ ] desktop file, spec file, and packaging scripts are in sync
11+
- [ ] visible UI changes have screenshots or notes for release context
12+
- [ ] there are no accidental debug prints or temporary workarounds left in the app
13+
14+
## Choose a version
15+
16+
Use semver-style tags:
17+
18+
- patch: `v0.1.1` for fixes and small polish
19+
- minor: `v0.2.0` for visible features or workflow improvements
20+
- major: `v1.0.0` for breaking or milestone releases
21+
22+
## Create the release
23+
24+
```bash
25+
git tag v0.1.1
26+
git push origin v0.1.1
27+
```
28+
29+
This triggers the GitHub Actions release workflow, which:
30+
- runs the build in Docker
31+
- produces the RPM
32+
- uploads workflow artifacts
33+
- creates a GitHub Release
34+
- attaches the RPM and `SHA256SUMS.txt`
35+
36+
## Manual release option
37+
38+
If needed, use the GitHub Actions **Release RPM** workflow manually and provide:
39+
- `0.1.1` or `v0.1.1`
40+
- prerelease flag if appropriate
41+
42+
## After release
43+
44+
- [ ] confirm the GitHub Release exists
45+
- [ ] confirm the RPM downloads correctly
46+
- [ ] confirm `SHA256SUMS.txt` is attached
47+
- [ ] spot-check install instructions from README against the released artifact name
48+
- [ ] if this is a notable UX change, add screenshots to the README or release notes
49+
50+
## Nice-to-have follow-up
51+
52+
- [ ] note known issues in release notes if there are desktop-environment-specific quirks
53+
- [ ] open follow-up issues for deferred cleanup rather than hiding them in memory

0 commit comments

Comments
 (0)