Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
100 lines (70 loc) · 3.88 KB

CONTRIBUTING.md

File metadata and controls

100 lines (70 loc) · 3.88 KB
Raw

Contributing to Focus Timer

Thanks for considering contributing! Whether you're fixing bugs, translating, or adding features, your help is incredibly valuable.

Reporting issues

Found a bug? Please check the Troubleshooting section first.

When opening an issue on GitHub, include:

  • App version
  • Desktop environment and version
  • Relevant logs or a stack trace
  • Steps to reproduce the bug

Suggestions and feature requests are always welcome!

Troubleshooting

Missing indicator

If you're on GNOME, you'll need the Focus Timer extension. Check its troubleshooting page if you already have it.

Missing Automation panel

If you installed the app via Flathub, restricted permissions hide this panel. Try another installation option if you need it.

Getting logs

Since boot:

journalctl --user -b -t io.github.focustimerhq.FocusTimer

Real-time:

journalctl --user -f -t io.github.focustimerhq.FocusTimer

With debug output. Run in the terminal and reproduce the issue:

flatpak run io.github.focustimerhq.FocusTimer --quit
flatpak run --env=G_MESSAGES_DEBUG=focus-timer io.github.focustimerhq.FocusTimer

Getting a stack trace

If the app crashes, providing steps to reproduce it is usually enough. However, to share a stack trace, install the debug info:

flatpak install --user --include-sdk --include-debug io.github.focustimerhq.FocusTimer

Find the app PID from recent crashes:

coredumpctl list --since=today focus-timer

Run gdb with your <pid>:

flatpak-coredumpctl -m <pid> io.github.focustimerhq.FocusTimer

Inside gdb, get the full trace:

bt full

Translating

We use Gettext, with .pot and .po files located in the po/ directory. Note that the app and the GNOME Shell extension have separate translations.

To add or update a language:

  1. Generate or update your language's .po file in po/ (e.g., using msginit).
  2. Add your language to the po/LINGUAS file.
  3. Submit a Pull Request.

LLM prompt to ease the process:

Fill-in missing translations and update fuzzy translations for the given file. Translations are for an desktop Pomodoro timer app. Take care to use consistent same translations for words: "break", "pause", "start", "stop", "rewind", "interruption". "pause" refers to the timer action, while "break" refers to taking a break from work, "interruption" refers to a distraction. Translations does not need to be exact, but must convey same meaning - make them sound natural. Mark modified entries as fuzzy. Output the updated .po file for download, do not truncate it.

Note: We keep .po files synced with the .pot template automatically, so you don't need to do this manually.

Development

We recommend using GNOME Builder with the provided Flatpak manifest.

When running Devel manifest some features will not work, including notifications and background indicator. SQLite database will be separate from user session.

Running unit tests

Run:

ninja -C build test

or run unit tests through your IDE.

Useful Resources