Mini project 2024: Easy command history navigation through the History browser panel

Title:	Easy command history navigation through the History browser panel
Student Name:	Linda Karlovska
Organization:	​OSGeo - Open Source Geospatial Foundation
Mentor Name:	Anna Petrasova, Martin Landa
GitHub Repository:	​view repository
Budget:	1000 € (via GRASS GIS ​Student Grants)

Abstract

This project builds upon the work initiated during the OSGeo sprint in Prague in the summer of 2023 which involved creating a new History Browser panel facilitating the access to command history. Starting December 8th, the new History Browser panel is already available in the GRASS development version (see the PR ​https://github.com/OSGeo/grass/pull/3234). However, it offers only a simple single-level display of commands from the history log and the option for launching module dialogs pre-filled based on the command history.

Goal

The core part of the work will be devoted to expanding the basic functionality of the History Browser by providing the following enhancements:

• Changing the plain text format of the history log (.wxgui_history) to JSON, allowing more information to be stored for each executed command, such as execution time, runtime duration, status code, region settings, if a mask was set, etc.

• Creating a context menu with options for "Run Command" and "Show Info." "Show Info" will display a small dialog about the respective process stored in the JSON file.

• Adding a symbol (green checkmark, yellow dot, or red cross) in front of each command in the tree based on the command's status value (completed, in progress, failed).

• Branching the tree based on the date of command execution (commands from a specific day could be rolled up).

• Filtering commands based on the status (completed, in process, failed)

Timeline

Time Period	Milestones
	Tasks	Status
January 8 - January 12 Week 1	Add pop-up command menu with an item for delete command from history + history tree refactoring ​https://github.com/OSGeo/grass/pull/3342	Merged
January 15 - January 19 Week 2	History tree refactoring ​https://github.com/OSGeo/grass/pull/3342	Merged

January 22 - January 26 Week 3	Changing the plain text format of the history log (.wxgui_history) to JSON and showing info about the command from history ​https://github.com/OSGeo/grass/pull/3365	Merged

January 29 - February 2 Week 4	Showing info about the command from history and relocating Export History button from Console to History pane ​https://github.com/OSGeo/grass/pull/3365 ​https://github.com/OSGeo/grass/pull/3402	Merged Merged

February 4 - April 12 Week 4	Maternity gap :-)

April 8 - April 12 Week 5	New button for setting current computational region based on executed commands; Branching the tree based on the date of command execution ​https://github.com/OSGeo/grass/pull/3421 ​https://github.com/OSGeo/grass/pull/3622	Merged Merged

April 15 - April 19 Week 6	Branching the tree based on the date of command execution ​https://github.com/OSGeo/grass/pull/3622	Merged

April 22 - April 26 Week 7

Branching the tree based on the date of command execution ​https://github.com/OSGeo/grass/pull/3622

Merged

April 29 - May 3 Week 8

Adding a symbol in front of each command in the tree based on the command's status (completed, in progress, failed, aborted) ​https://github.com/OSGeo/grass/pull/3679

Merged

May 6 - May 10 Week 9

Adding a symbol in front of each command in the tree based on the command's status (completed, in progress, failed, aborted) ​https://github.com/OSGeo/grass/pull/3679

Merged

Progress reports

Report for weeks 1 and 2

1) What did I complete?
The first simple implementation of the history browser panel (see ​https://github.com/OSGeo/grass/pull/3234) had some flaws, mainly in terms of class hierarchy, so a bigger intervention was needed. So, week one was all about making the code neater and more logical. I dived into improving the code quality and logic as part of the PR ​https://github.com/OSGeo/grass/pull/3342 since in this PR the problematic structure was fully shown. At the beginning of the second week, this PR adding a new pop/up command menu with an item for deleting a command from history was successfully merged. Big thanks to Tomas Zigo for the suggestions and testing!

In the middle of the second week, I started to prepare the biggest PR of this project ​https://github.com/OSGeo/grass/pull/3365 which focuses on two things: first, it changes the way how the new history log is stored - newly it is going to be the JSON format. Second, it shows the info about commands - execution time, runtime duration, status, region settings, and if a mask was set. We originally planned to show this info in a new Command Info dialog (see Figure 1), but during the implementations, we decided that it would be cooler to have it right at the bottom of the history browser.

2) What am I going to achieve for the next two weeks?
I'm sticking with ​https://github.com/OSGeo/grass/pull/3365 for the next two weeks. Firstly, the JSON format structure needs revisions. Secondly, I will rework how the info shows up - the info will be shown directly at the bottom of the history browser after calling OnItemSelected event. As this PR is the most important part of the project, it will probably require a couple of iterations.

3) Is there any blocking issue?
No, it isn't.

Report for weeks 3 and 4

1) What did I complete?
I worked on the PR ​https://github.com/OSGeo/grass/pull/3365 which addresses two things - it changes how the history log is stored - newly it will be the JSON format. Second, it shows info about commands in the history pane (finally created as the panel inside the History pane, see the right part of Figure 2). During this week, we decided that the original plain text history file would be automatically converted to a JSON file when launching a new command so that everyone would now seamlessly encounter command information. The initial concept was to create a JSON file only when establishing a new mapset, leaving previously created plain texts unchanged. PR ​https://github.com/OSGeo/grass/pull/3365 is currently awaiting review. Additionally, I have shared the PR ​https://github.com/OSGeo/grass/pull/3402 for relocating the "Export History" button from the Console to the History pane.

2) What am I going to achieve for the next two weeks?
I would like to merge both ​​https://github.com/OSGeo/grass/pull/3365 and ​https://github.com/OSGeo/grass/pull/3402. Following this, I plan to shift my focus towards Region settings. The objective is to enable users to set the current region based on the region from a history command, either through the context menu or using a button (details to be discussed). As the history command is currently rerun with the current region, I also aim to implement an option to rerun it with the original region.

3) Is there any blocking issue?
No, it isn't, but I am just in the last two weeks of pregnancy :-) So, I might be a bit less active in the upcoming weeks.

Report for weeks 5 and 6

1) What did I complete?
1) What did I complete? I completed the PR ​https://github.com/OSGeo/grass/pull/3365 which enables storing more information about executed commands. Newly, commands are stored in JSON format and then displayed as the command info in the history pane. I also completed the relocation of the Export History button from the Console pane to the History pane (​https://github.com/OSGeo/grass/pull/3402).

Besides that, I am working on ​https://github.com/OSGeo/grass/pull/3421 and ​https://github.com/OSGeo/grass/pull/3622. The first PR creates a new button for setting the current region to the region used during the command execution. This PR is awaiting the final review. The second contribution adds time branching to the history browser tree and is currently waiting for the review.

2) What am I going to achieve for the next two weeks? I want to merge both ​https://github.com/OSGeo/grass/pull/3421 and ​https://github.com/OSGeo/grass/pull/3622. Subsequently, I plan to shift my focus toward visualization of command status. I plan to add icons in front of command nodes representing possible states (success, failed, in process, aborted). Regarding the status, it would also be nice to show the complete error text if a command fails. (Now there is “failed” written but no clue what happened).

3) Is there any blocking issue? No, it isn’t. I have been much more busy the last two months since on the 19th of February, my two-member family was expanded by one little guy, my son Vilem. So any work has gone kind of slowly over the last two months… :-)

Report for weeks 7,8 and 9

1) What did I complete?
I completed PRs ​https://github.com/OSGeo/grass/pull/3622 implementing time node branching in the history tree, organizing commands from oldest to newest. Moreover, I also added a button to update the current region based on the region used during command execution (PR ​https://github.com/OSGeo/grass/pull/3421). Besides that, I introduced icons representing command status (success, failed, running, aborted, unknown) and added them in front of history entries (PR ​https://github.com/OSGeo/grass/pull/3679). Thanks Anna for the valuable comments in reviews!

Final Report

Title: Mini project 2024: Easy command history navigation through the History browser panel
Community: GRASS GIS - OSGeo

Abstract:
This project builds upon the work initiated during the OSGeo sprint in Prague in the summer of 2023, which focused on creating a new History Browser panel to facilitate access to command history. Although the new History Browser panel became available in the GRASS development version starting December 8th (refer to PR ​https://github.com/OSGeo/grass/pull/3234), initially it provided only a basic, single-level display of commands from the history log, with the capability to relaunch commands but lacking detailed command information. This project aims to enhance the basic functionality by incorporating several improvements.

The state of the art BEFORE the start of the Mini project:
The History Browser panel displayed a simple tree of command entries loaded from a plain-text history log. It had only the capability to relaunch commands.

The state of the art AFTER Mini project:
Implemented changes include:

• Transitioning the plain text format of the history log (.wxgui_history) to JSON format, allowing more information to be stored for each executed command. Newly, the log stores information about the timestamp (the exact time when a command was launched), command status (success, failed, running, aborted, unknown), runtime duration, region settings, and mask usage (was set/ was not set).

• Instead of implementing the context option "Show Info" and displaying a small dialog with process information, the history pane was redesigned into two sections. The upper part features the history tree, while the lower part includes two static boxes presenting information stored in the history log. The first box contains general details, and the second box displays the computational region during command execution.

• Adding a symbol in front of each command in the tree based on the command's status.

• Branching the tree based on the date of command execution - tree is branched into days and sorted from the Today node to older nodes. Command nodes are sorted from the oldest to the newest.

The task of filtering commands based on status was not addressed during the project due to higher-priority issues that emerged:

• Adding the "Update current region" button, which dynamically updates the region based on the executed command and its information stored in the JSON-formatted history log.
• Introducing a new Delete option in the command tree
• Rearranging the Export History button

Next Steps:
Possible improvements for the History browser pane:

• Fixing of command status for nonsense entries (already noted here ​https://github.com/OSGeo/grass/issues/3698)
• Sorting the commands in the history tree from the newest to oldest (seems more logical)
• Implementing efficient refresh methods (currently all nodes are refreshed when adding a command)
• Showing the complete error text if a command fails. (Now there is a “failed” status written but no clue what actually happened).
• Adding the new combo box restricting the filtering based on the command status
• Adding the Copy context menu option to command nodes

Permanent Links:

Title	Pull Request	Issue
wxGUI/history: Add pop-up command menu with an item for delete command from history + history tree refactoring	​https://github.com/OSGeo/grass/pull/3342	-	MERGED
wxGUI/history: Create panel displaying info about command	​https://github.com/OSGeo/grass/pull/3365	-	MERGED
wxGUI/history: Move Export History button to history pane	​https://github.com/OSGeo/grass/pull/3402	-	MERGED
wxGUI/history: New button for setting current computational region based on executed commands	​https://github.com/OSGeo/grass/pull/3421	-	MERGED
wxGUI/history: Add time period branching to history browser tree	​https://github.com/OSGeo/grass/pull/3622	-	MERGED
wxGUI/history: Add time/status icons in front of browser nodes	​https://github.com/OSGeo/grass/pull/3679	-	MERGED

Progress Reports:
​https://trac.osgeo.org/grass/wiki/wxGUIDevelopment/EasyCommandHistoryNavigation

Screenshots of History Browser improvements