Add changelog/announcements to the GUI

[roomrys]

Discussed in https://github.com/talmolab/sleap/discussions/1492

^{Originally posted by roomrys January 5, 2023}

Problem background

• Many users download SLEAP once and never look back.
• Very rarely will users keep tabs on the new releases of SLEAP and rush to get the latest version.

Feature proposal

• We should keep track of the latest SLEAP changelog (and other announcements) on the sleap.ai page.
• Then, we can reference the url to this webpage from within the SLEAP codebase to update messages to the user.
• New messages can then be displayed without needing to update the version of SLEAP.

Implementation details

For this feature, we will just be retrieving the changelog and displaying this message in SLEAP. Checkout this example repository which shows Proof of Concept.

PR 1 (Skip for Hackathon MVP): Add a changelog/announcements page to sleap.ai

SLEAP uses sphinx to generate documentation (the sleap.ai page) for the codebase. We are currently in the process of converting all our documentation from reStructuredTest to Markdown. SLEAP uses MyST, "a rich and extensible flavour of Markdown", which has some cool features that regular markdown doesn't have.

1. Create a bulletin.md file in the docs folder

This file will be used to display any news (and new release info) the developers wish to convey to the user.

• [ ] Use extended MyST syntax where needed/useful
• [ ] Copy over the SLEAP changelog for the latest version from the Github releases page.
• [ ] The first line should be the heading: # Bulletin (this is used as the link name in the next step)

2. Add a new link to the main sleap.ai page called "Bulletin"

• [ ] List the relative path to bulletin.md inside index.rst.

PR 2: Check for and grab new announcements in SLEAP

1. Add a variable to be stored past the program runtime which remembers when the user has last seen an announcement

Ever wonder how SLEAP remembers user preferences, such as which color scheme to use, even after the user closes (and reopens) the program? SLEAP stores these preferences in a hidden folder called .sleap at the User's root directory. Whenever a new version of SLEAP is installed on a user's computer, a new folder is created within the .sleap directory which stores the user's preferences for that version of SLEAP. If the files preferences file does not exist yet (a fresh install of the latest SLEAP version), then SLEAP will create the preferences based on the defaults set in the singleton class Preferences: https://github.com/talmolab/sleap/blob/c4861e3a18d39635f1214f3bc9c46415557c861f/sleap/prefs.py#L10-L74

• [ ] Add a new "preference" to the _defaults dictionary which will store the date of last seen announcement in the format YYYYMMDD.
• [ ] Update the app's state using the preference as done with other state/pref pairs below: https://github.com/talmolab/sleap/blob/c4861e3a18d39635f1214f3bc9c46415557c861f/sleap/gui/app.py#L148-L161
• [ ] Save the preference upon closing the MainWindow https://github.com/talmolab/sleap/blob/c4861e3a18d39635f1214f3bc9c46415557c861f/sleap/gui/app.py#L211-L220

2. Create a AnnouncementChecker class to check for and fetch new announcements

The sleap/gui/web.py module contains all web related interactions handled by SLEAP. We will modify this module to check for new announcements. The AnnouncementChecker class should:

• [ ] Check if there has been a new announcement since the last SEEN announcement
• [ ] Fetch the announcement if there is a new UNSEEN announcement
• [ ] Update the app's state of when an announcement was last seen.

PR 3: Display changelog/announcement page in SLEAP GUI

After we've fetched the announcement, we now need to display it in the GUI.

1. Create a simple dialog that displays the announcement.

All dialogs/pop-ups are created in the sleap/gui/dialogs folder as their own modules. For example, checkout the ShortcutDialog class: https://github.com/talmolab/sleap/blob/c4861e3a18d39635f1214f3bc9c46415557c861f/sleap/gui/dialogs/shortcuts.py#L12-L110

• [ ] Create a new file bulletin.py and class BulletinDialog to display the announcement.
• [ ] Create an instance of this BulletinDialog class while initializing the MainWindow IF there is an UNSEEN announcement.

PR 4: Add a Help Menu item which allows users to pop-up the announcement on demand.

Whenever a user calls upon any GUI commands, SLEAP's CommandContext in conjunction with the AppCommand class handles the call using a Command design pattern. https://github.com/talmolab/sleap/blob/c4861e3a18d39635f1214f3bc9c46415557c861f/sleap/gui/commands.py#L176-L574 https://github.com/talmolab/sleap/blob/c4861e3a18d39635f1214f3bc9c46415557c861f/sleap/gui/commands.py#L85-L165

1. Create a new class ShowBulletin(AppCommand) which displays the bulletin when ShowBulletin.execute() is run.

• [ ] Create a do_action method which creates an instance of BulletinDialog
• [ ] Create a CommandContext.bulletinDialog() method which executes BulletinDialog

2. Add a "Show Bulletin" button to the help menu

The help menu is created here: https://github.com/talmolab/sleap/blob/c4861e3a18d39635f1214f3bc9c46415557c861f/sleap/gui/app.py#L889-L927

• [ ] Add an action to the helpMenu with title "Show Bulletin" and action self.commands.showBulletin