Skip to content

Latest commit

 

History

History
161 lines (127 loc) · 5.86 KB

Development.md

File metadata and controls

161 lines (127 loc) · 5.86 KB

Pygenda Development

Miscellaneous hints/notes for development.

Installing in Development mode

In Python, you can install modules in Development (Editable) mode with:

pip3 install --editable . [--user]

Or, for older versions of pip3 (e.g. on Gemini, Cosmo):

./setup_old.py develop --user

Rather than copying the application files, this creates a link to the source directory, so any changes you make in the source are instantly available in the "installed" version.

Clipboard library

This is a small C library to improve cutting/copying behaviour. Specifically it allows Pygenda entries to be copied+pasted as text into applications that expect text, and as calendar entries into applications that expect calendar entries. Tested on Gemian, postmarketOS and Slackware, and probably works on other Linux distributions. It might need tweaking for Windows/MacOS/BSD/other.

In order to be as universally compatible as possible, the clipboard library is not included in the default wheel package. However, you can build the library yourself, and if you are packaging Pygenda (e.g. for a specific OS or a Flatpak) it is recommended that you include an appropriate version of libpygenda_clipboard.so for improved functionality.

To build and copy to the correct location in the source tree:

cd csrc
cmake .
make
make cp

Build dependencies are: a C compiler, make, CMake (or you could build by calling your compiler directly), development files for your libc (e.g. libc-dev, or musl-dev on postmarketOS) and GTK3 development files (if these are not already installed, it's probably package libgtk-3-dev or gtk+3.0-dev in your package manager).

Translating strings

Use the provided pygenda/locale/pygenda.pot file to create/update the .po for the target language.

Existing languages:

cd pygenda/locale
msgmerge -U fr/LC_MESSAGES/pygenda.po pygenda.pot

To add new languages:

cd pygenda/locale
msginit -i pygenda.pot -o de/LC_MESSAGES/pygenda.po -l de_DE

Check/edit the generated .po files, maybe adding translations.

Process each .po to generate the .mo:

cd fr/LC_MESSAGES
msgfmt pygenda.po -o pygenda.mo

In general, use the locale/pygenda.pot provided (since the automatic tools don't find all the strings, and you'll need to check/edit/add things). However, if you have added, removed or changed strings, and wish to generate a pygenda.pot, in the pygenda subdirectory:

xgettext --package-name Pygenda --copyright-holder "Matthew Lewis" -k_ -kN_ -o locale/pygenda.pot *.py ui/*.ui

Then compare against the previous pygenda.pot and integrate any strings that xgettext missed.

Checklist for releases

  • Check new code is appropriately commented and annotated
  • Check any doc changes made (e.g. known issues, config, this checklist)
  • Run mypy . in source directory, check any new messages
  • If any new dependencies are required, add them to pyproject.toml
  • Check any new files are included in wheel & tar.gz generated by python3 -m build
  • Check python3 -m build then pip3 install dist/pygenda-*.whl works and the wheel installs & runs correctly on various devices (also check in a venv - this will test with latest versions of dependencies)
  • Create various events & todo items. Close & reopen Pygenda and check they are still there (with iCal file, EDS, & CalDAV server).
  • Check copy/cut/paste works, including e.g. event date/time, multi-day events, event status, with alarms, with notes, with location, todo pasted as event & vice-versa, text pasted
  • Check importing events, todos, and repeated events work
  • Check readonly calendars work - missing from calendar dropdown, can't edit entries, if all readonly then can't create entries
  • Regenerate .po and .mo localisation files (see above)
  • Check at least one non-English language
  • Check any iCal files in validator, e.g. https://icalendar.org/validator.html
  • Run test_entries.py, test_repeats.py, test_import_paste.py & test_ongoing.py unit tests
  • Check all test files (testxx_*.ics & generated files) display correctly
  • Check darkmode & backgrounds CSS still work
  • Check mouse clicks/touchscreen taps/swipes work (all views)
  • Check start_week_day!=Monday still works (all views)
  • Increase version number in pygenda_version.py & pyproject.toml

Checking repeats

In addition to test_repeats.py unit tests... Repeated event display can be checked by hand (plan to automate later) by enabling checking in repeats_in_range() method (file pygenda_calendar.py) and skipping through the test02_repeats.ics file. (Try Year View.)

Debugging

  • On Gemini:

    sudo apt install libgtk-3-dev gsettings set org.gtk.Settings.Debug enable-inspector-keybinding true

    Launch Pygenda & press ctrl+shift+d

  • Other Linux (tested on Slackware):

    GTK_DEBUG=interactive python3 -m pygenda

Test packaging

You can test packaging using a virtual Python environment:

# In root directory of Pygenda source, build a wheel
python3 -m build
# Set up and activate the virtual environment
cd ~
python3 -m venv venv_dir
source venv_dir/bin/activate
# Install the wheel
cd PYGENDA_SRC_DIR
pip3 install dist/pygenda-*.whl
# Check no install errors
cd ~
# Check pygenda runs with a file
python3 -m pygenda -f test.ics
# (Optionally install caldav and check pygenda can use it)
# Exit and tidy up
deactivate
rm -r venv_dir

Logging

To log errors when Pygenda is launched from an icon, change the .desktop file used to launch Pygenda so that the Exec line reads:

Exec=bash -c "python3 -m pygenda 2>>FULL_PATH_OF_PYGENDA_LOG_FILE"

You may also want to log errors from whatever server you are using. For Radicale, edit the .desktop file in ~/.config/autostart/:

Exec=bash -c "python3 -m radicale 2>>FULL_PATH_OF_RADICALE_LOG_FILE"