
Publisher
ace24713
Sticky Scribe - A flexible TODO list, task manager, bug tracker, and notes tool for Godot 3
Sticky Scribe is a light-weight TODO list and bug tracker, designed for solo devs and small teams. It integrates directly into Godot, and maintains a text list of "Stickies" in your project directory that is designed to be checked in to version control. Stickies are like tickets, but they're purpose agnostic and could be used to track tasks, bug reports, or notes. Sticky Scribe uses a human-readable json format that is friendly for manual editing and merging if necessary. Sticky Scribe has ma...
Sticky Scribe
What is Sticky Scribe?
Sticky Scribe is a light-weight TODO list and bug tracker, designed for solo devs and small teams. It integrates directly into Godot, and mastertains a text list of "Stickies" in your project directory that is designed to be checked in to version control. Stickies are like tickets, but they're purpose agnostic and could be used to track tasks, bug reports, or notes. Sticky Scribe uses a human-readable json format that is friendly for manual editing and merging if necessary. Sticky Scribe has many quality of life improvements over a basic TODO txt file at the cost of minimal file size increase and editing complexity.
...and what isn't it?
Sticky Scribe is NOT designed to be a replacement tracker for larger scale projects with many team members. It is not designed to replace an Agile or Scrum board, as it lacks many of the overview analytic tools that would be useful to team managers. In direct contrast, Sticky Scribe's design philisophy is to make it as effortless as possible to record new tasks or bugs. Personally our small development team felt burdened by the extra steps required to use existing ticket trackers. Now with Sticky Scribe we no longer take notes in notepad to be later converted into formal tickets, we simply take our notes as Stickies directly.
Feature Overview
- Sticky Scribe embeds into Godot engine as a master panel tab, so you always have quick and convenient access to your sticky list.
- Stickies are presented in a condensed view that shows the first line of the description as well as features, priority, and estimate if given. The list can be sorted, searched, and filtered.
- If default filtering options are insufficient you can use any valid gdscript expression as a boolean filter, enabling complex options without requiring an understanding of Regex.
- Clicking a sticky expands into editing mode where you can see the Timestamp and Author, as well as edit the full sticky Text, Priority, Estimate, and Tags.
- Filtered stickies have their quantity and estimates (if provided) accumulated, so you can have a rough idea of how long it should take to finish the items in the list.
Installation
Download
The embedded Sticky Scribe plugin can be installed via the Godot Asset Library for Godot 3 or Godot 4. But you can alternatively download the latest addon package from the releases page. Be sure to download the appropriate sticky-scribe-addon-vX.X.X.zip
and not the source code link, which currently doesn't include the addon source because the addon code is in a submodule (see related GitLab issue). If you prefer, you can checkout that code as a submodule in your own project as well, which can be useful for contributors.
Enabling
Now that you have the source in res://addons/sticky_scribe
you can enable it from the Godot Plugins menu. Open Project > Project Settings then navigate to the Plugins tab to Enable Sticky Scribe.
Setup
The addon should be found in the top bar of the editor. From here you need to simply write your preferred name in the Author field and you can open stickies using the adjacent New button. Sticky Scribe will remember your name for future launches, and when you create your first sticky it will automatically create the file res://project.issues
for you. You may wish to do this early so you don't forget to check the file into your projects version control.
For more information about Plugins, refer to the Godot docs page.
Sticky Scribe Standalone
Sticky Scribe also suports a standalone version that runs outside of the Godot editor. This can be useful for non-godot projects, or if you have several sticky boards that you'd like to edit from one convenient location.
You can grab the latest standalone package from the releases page. The download should be labeled sticky-scribe-standalone-vX.X.X.zip
. You can extract the contents to any folder you like, keeping the contents of the windows
or linux
folder as appropriate.
Note the sticky-scribe.console.exe
in the windows
folder can be ran if debugging output is desired, which can be helpful specifically for debugging GD expression errors, but it needs to be kept in the same folder as sticky-scribe.exe
in order to work. Any messages that are sent to the Godot Output Panel will instead appear in the console.
Sticky Scribe Standalone is used in the same manner as the addon version, but unlike the addon version sticky boards need to be imported or created manually, in either case you would do so using the + button at the top of the window and specifying the file to open or create.
Features Breakdown
Adding Stickies
Before you can create Stickies you need to give yourself an Author name in the top right. Then any Stickies created via the adjacent New button will be opened under your name. It is important to use a distinct name from your team members because Sticky Scribe will create a unique section in it's project.issues
file for your stickies, which prevents merge conflicts when multiple authors create stickies at the same time. For normal use cases you shouldn't have to edit your Author name again, but if you do the change will only apply to future New Stickies. If you also wish to retroactively alter your Author name, it's relatively simple to do via manual find-replace in the project.issues
file, just be aware that if there are any Stickies already open with your new name, that the json blocks under issues > **** will need to be manually merged.
When adding a new sticky, it will always appear the top of the sticky list. It will ignore current sorting and filtering options and remaster at the top of the sticky board until the list is refreshed, re-sorted, or re-filtered.
Deleting Stickies
Stickies can be deleted using the Delete button to the right of each Sticky itself. This will cross out the sticky in the UI. The Delete button will turn into a Restore button which can be clicked to quickly un-delete the Sticky. Sticky Scribe will re-save the project.issues
file immediately with the deleted sticky absent. The Sticky will vanish from the UI the next time Sticky Scribe refreshes or the editor is restarted.
Crossed out stickies will sort and filter as normal.
Saving
Sticky Scribe saves automatically shortly after any edit is made, so you don't need to manually save your changes. We choose automatic saving because Sticky Scribe was intended to be used in version controlled projects, and in those circumstances forgetting to save your changes before committing or losing your changes due to an editor crash is more problematic than accidentally overwritting something.
Tagging
Tags are assigned via a comma-seperated list in the Tags section of a sticky. These are useful for various filtering options. If you wish, you can apply a color value to a named tag by right-clicking any instance of the tag button next to a sticky. Sticky Scribe doesn't have a dedicated "status" field for tracking concepts like "in-progress", "closed", "in-review", etc. Those concepts would be captured as Tags. The coloring system was introduced so that tag categories like status or asignee can be identified at a glance, but how you choose to use it is up to you. Coloring a sticky has no special meaning within Sticky Scribe, and there's (currently) no method to filter by tag color.
8 colors are available by default, but you can use any color you like by editing the meta > tag_colors block in project.issues
. Any colors manually added in will show up in the right-click ui for future use. The default 8 colors are:
$$\colorbox{black}{{\color{ffffff}white}, \space
{\color{ff6663}red}, \space
{\color{feb144}orange}, \space
{\color{fdfd97}yellow}, \space
{\color{9ee09e}green}, \space
{\color{9ec1cf}blue}, \space
{\color{cc99c9}purple}, \space
{\color{f49ac1}magenta}} $$
Priority
Priority can be assigned via the Priority field. These are useful for various filtering and sorting options. Floating point and negative values are accepted. The +/- buttons increment/decrement the value by 1
, and the Clear button removes the priority value, which is different than using a value of 0
. The priority bubbles on the sticky are color-coded according to relative severity. The color range will span whatever range of values exist in the sticky list. This is because for some teams 3
might be considered a relatively low value, while to others it might be high.
Estimate
Stickies can be assigned an estimate value from the Estimate drop-down. The value is stored as a number of calander days in the project.issues
file and can be manually edited to any value* if desired. Durations are measured in calendar days instead of work days for simplicity, and the limited default options are just meant as a means to categorize the rough weight of entries. Stickies can be sorted and filtered based on estimate length, and when a filter is applied the estimates for each sticky are added up and presented at the bottom of the sticky list. Although this can generate a specific length of time to get through a set of stickies, it's not designed to be very precise. I designed it this way because I felt systems like "story points" from agile process are designed for managers trying to ascertain precise development timelines, and for small teams like ours that extra complexity isn't worth paying for. Having a simple breakdown of small, medium, or large stickies is sufficient for tracking progress. The actual dropdown options are:
- I don't know (default) - An unassigned estimate value.
- a day - A small sticky with an estimate value of 1 calendar day.
- a week - A medium sticky with an estimate value of 7 calendar days.
- a month - A large sticky with an estimate value of 35 calendar days.
- a really long time - For oversized stickies, the estimate value is listed as a quantity of ∞ calendar days when accumulated, a social commentary about the meaninglessness of time in software development. 🙃
The estimate accumulation takes the form X±Y days
, where Y represents the uncertainty from unestimated stickies. Y and X are calculated as:
$$Y=\frac{# filtered \space unestimated \space stickies \cdot average \space estimate \space of \space filtered \space stickies}{2}, \space X=\sum{estimate \space of \space each \space sticky} - Y$$
As an example, if there are 8 stickies each with a 7 day estimate, and 2 with no estimate. The display would read 63±7 days
with the low-estimate of 56
representing the sum of the 8 estimated stickies, and the high-estimate 70
representing the low-estimate plus the guess that the unestimated stickies will take 7
days each.
* due to a quirk of the implementation on Godot's side that is annoying to work around, values greater than or equal to 4096 days are all counted as ∞ days when accumulated. Search the codebase for 4096
if you're curious about it.
Sorting
The sticky board can be sorted via the Sort By... button in the top left of the UI. Sorting will visually rearrange the stickies, but does not modify the project.issues
file. When sorting between two stickies is ambiguous, the current order is preserved. This makes subsorting the sticky list possible by selecting sort options back to back. For example, selecting Sort By... > Author then Sort By... > High Priority First will result in a list in which high-priority stickies are at the top, and stickies with the same priority are sorted by author. Sorting options:
- Oldest Priority First (default) - Sort by priority, subsort by date. Same as selecting Oldest First then High Priority First in order.
- High Priority First - Sort by priority, with the highest numerical values at the top. Undefined priority stickies are always at the bottom.
- Low Priority First - Exactly the reverse of the above. Undefined priority stickies are always at the top.
- Oldest First - The stickies are sorted by creation timestamp, with the oldest stickies being at the top. The timestamp is fixed when the sticky is created, and does not change when modified.
- Newest First - Exactly the reverse of the above.
- Shortest First - The stickies are sorted by estimate, with the lowest estimate stickies at the top. Stickies with undefined estimate are always at the top.
- Longest First - Exactly the reverse of the above. Stickies with undefined estimate are always at the bottom.
- Author - Sort by author name in alphabetical order. As with all sorting methods, the order of stickies with the same author is mastertained from the previous ordering.
Filtering
There are several methods that can be used to filter the sticky list. Only stickies that satisfy all filtering options will be shown. There are two methods of filtering standard and GD filtering. Standard is designed to cover basic use cases for quick and easy filtering, but for more specific control GD script expression can be used. Standard filtering is implemented via GD filtering, so when you change modes you will see the previously generated expression exposed for editing.
Standard Filtering
The standard view shows filtering options for Tag Filter, Priority Filter, and keyword Search filter.
Tag Filter
The Tag Filter field accepts a comma-seperated list of tags. Stickies will only be shown if they contain any of the listed items as tags or as substrings of tags. The substring clause is useful in the case where you might have several similar tags. As an example, suppose you had the tags bug
and xbug
, then filtering by the keyword bug
would capture both.
Priority Filter
Priority can be filtered out using the Priority dropdown, and a target value in the adjacent spinbox (when applicable). The following dropdown options are available:
- Any (default) - All priority values are shown, no filtering is applied, and the value spinbox is hidden.
- >= - Only stickies with a priority greater than or equal to the target value will be shown. Stickies with no assigned priority are also hidden.
- , test : Array) -> bool - true if any element in check contains any element in test as a substring
- contains_regex(check : String, pattern : String) -> bool - true if an occurrence of the regex pattern is found in check
- any_contains_regex(check : Array, pattern : String) -> bool - true if an occurrence of the regex pattern is found in any element in check
After typing your expression and pressing Enter
Sticky Scribe will attempt to apply the filter. If the expression is syntactically valid the text box will turn green. If there was an error it will turn red and the error will show in the Godot Output Panel. The text field will turn back to normal when you edit it again.
Refreshing
Sticky Scribe will automatically check for modifications and refresh whenever the editor regains focus. Pulling changes in git often results in modifications to project.issues
while Sticky Scribe is open. If modifications are detected the sticky board is refreshed. Note that any expanded Stickies will be minimized, and the scrollbar position might be different. If Sticky Scribe encounters an unexpected issue when refreshing, such as invalid syntax in the project.issues
, it will log an Error in the Godot Output Panel and will not attempt to save or load changes until it's resolved.
Resolving Merge Conflicts
Sticky Scribe's project.issues
file is designed to be merge friendly and human readable through clever usage of standard json format. Most of the time automatic merge process should be able to resolve any problems, particularly for cases where different authors opened or edited different stickies. In some cases it may be necessary to manually merge the files, in which case a basic understanding of json format is helpful.
Manual merge may be required if:
- both change sets assign colors to new Tags
- both change sets include an Author's first sticky
- both change sets edit the same sticky's text or properties
- both change sets include new stickies by the same Author
- ... and probably some other unknown cases too (file merging can be a little fickle sometimes)
Support and Contributions
Bug Reports and Feature Requests
If you have any bugs to report or features you'd like, feel free to open an issue on the issue board. Please note, this project is divided into two repositories, this one is the master repo for releases and the standalone code, but the issue board can be found in the addon repository which contains most of the code for Sticky Scribe. If the ticket you wish to open is unique to the standalone release, you can still open it on the addon's issue board for the time being, as there isn't a public issue board for this repo. It is perhaps a bit ironic to use gitlab's issue tracker for software that is literally an issue tracker, but as described above Sticky Scribe isn't designed for public facing ticket submission. Regardless, I do keep an internal list of wanted features and bugs in this project's project.issues file.
If you need help with setup or usage of Sticky Scribe, for now you can also just open an issue on the issue board with your question. I may want to add it to an FAQ if I think it's noteworthy.
Merge Requests
Code contributions are also welcome in the form of Merge Requests, though I don't have any formalized process in place for approving them at this time, so I'll get to it eventually. This repository contains the code for the standalone release, if you have code contributions specifically for that, you can make them here. Otherwise contributions for Sticky Scribe addon and core code can be made against that repository over here.