goingforbrooke / folsum

Summarize the contents of a directory by filetype.

goingforbrooke.com

👩🏼‍🔬 My Open Source Projects

🤝🏻 Open Source Projects that I've Contributed To

folsum's Issues

Document Pull Request Flow

Issue

Contributors don't have a workflow for PRing this repo.

Legacy

Adding PRs to the CI pipeline would make it easier to add release notes for each release. Release notes are currently placeholder text "add feature X" and "fix buy Y."

Fix

Document PR flow (branch off of dev and PR merge (--no-ff) to main) in README.md's "Contributing" section.

WASM: Grey-out incompatible buttons

Issue

In the WASM build, buttons for operations that interact with the local filesystem are removed.

Solution

Grey out these buttons in WASM builds.

Add Windows Compatibility

Issue

A user requested that FolSum be made available for running on Windows systems.

Solution

Add Windows to the CI/CD pipeline.

Automatic Dependency Upgrades

Issue

Dependency updates are annoying to do by hand, much less remember that they need to be done.

Solution

Add a CI/CD step that checks for dependency updates and updates FolSum automatically. Upgrade attempts should fail if tests don't pass. As a bonus, they should also fail if there's output from cargo check, which would indicate that a dependency's API changed or is about to change, and so needs developer attention.

There's an opportunity here to merge in security-critical patches sooner (and independently of scheduled upgrades), but that might be a bit too complex.

User Feedback Submissions

Issue

The loop on getting feedback from users is large and slow.

Solution

Create an in-app feedback system.

• include dump of log files
• destination ideas
  • Digital Ocean function and/or bucket"
    • other platforms add project complexity
  • Repo Issues
    • could get spammy

Add CI/CD Badges to `README.md`

Issue

The repo would look more professional if it had some CI/CD badges to report on the status of different pipelines. It would also serve as a "developer dashboard" to identify build failures more quickly. Contributors might feel more compelled to contribute if they see that the repo has recent activity.

Solution

Add CI/CD badges to READM.md.
Ideas:

• use eFrame workflows for inspiration
• number of issues
• build passing/failing for each supported platform
• testing coverage percentage
• last commit: X days ago
• documentation tests passing/failing
• downloads count
• inspiration

WASM: Add Test Files Demo

Issue

WASM builds display the GUI nicely in-browser, but new users should be able to meaningfully interact with the application so they can get excited about how it works.

Solution

Add some test files to WASM deployments so browser users have something to summarize. Don't bother with uploading their own files-- that's outside the scope of this project.

Descending Order in CSV Exports

Issue

CSV exports don't match what's displayed in the GUI. Instead of ordering by descending order (like the GUI), they're in the order that they were added. Users will expect the most populous file extensions to be at the top.

Solution

Create CSV exports with file extensions in descending order.

Bug: CSV Columns Swapped

In CSV exports, the columns names for the extension names and the counts are reversed.

CI/CD: Measure Bloat On Each Build

Issue

It's hard for maintainers to weigh the cost of adding dependencies, at least as they relate to binary size.

Solution

Measure the size of the built binary and the dependencies. This was inspired by this action, though it uses TypeScript, and should really be written in rust as a dev dependency.

File Dialog Freezes GUI (needs `async`)

Issue

Opening a file dialog freezes the GUI. This doesn't matter very much because investigators probably aren't looking at the GUI while they're picking files, but it looks unprofessional.

Solution

Asynchronously spawn file dialogs so they don't block the GUI.

Integrate eFrame Template Updates

Issue

eFrame has some new updates.

• egui_README.md: update sw.js
• swap entire egui_README.md for eframe's up-to-date one

Add Donation Button

Issue

This is free software, but investigators don't have an avenue to show their gratitude by parting with green slips of paper.

Solution

Add a donation button to README.md. Things to look into include Patreon, PayPal, GitHub subscriptions, and that cute "Buy Me a Coffee" button that I keep seeing.

Add CI/CD Version Bump Debug Annotations

Issue

When CI/CD pipelines fail, the first thing that I want to know is whether it was trying to increment the minor or patch/fix (SemVer) version.

Solution

Use ::notice:: to annotate the output of the following CI/CD steps in build_macos.yml:

• Steps
  • Get the last branch that was merged into the dev branch
  • Decide whether to bump the minor or patch version
  • Increment minor/patch version

      - name: Generate "new release" message with hyperlink to release page
        id: generate_release_message
        run: echo "message=Created new release ${{ steps.get_bumped_semver.outputs.semver }} at ${{ steps.publish_release.outputs.html_url }}" >> $GITHUB_OUTPUT
      - name: Create info message about new release
        run: echo "::notice::${{ steps.generate_release_message.outputs.message }}"

CI/CD: Dynamic Auto-commit Message

Issue

The CI/CD pipeline's auto-commit message for version bumping says minor when the patch/fix version version was incremented.

Ex.
499f182 Increment minor version from v2.0.0 to v2.0.1

Solution

Dynamically change the auto-commit message based on the type of version bump.

Speed Up Clones

Issue

Clones could probably go faster. Ref article

Solution

Add refspec to clone in CI.

CI/CD: Block without Changelog

Issue

The CI/CD pipeline published releases even if CHANGELOG.md hasn't been updated. This will make it harder to identify bugs down the road. It'll also make it harder to "sell" investigators on updating to the next version.

Solution

Fail to publish a release if CHANGELOG.md hasn't been update. Use keepachangelog.com as inspiraton.

Refactor `unlocked` Variable Names to `locked`

Issue

Many mutex locks are erroneously named unlocked, when really they're locking the mutex, not unlocking it.

Solution

Rename mutex guard variables prefixed by unlocked to locked.

Block CSV Export if Nothing's Been Summarized

Issue

If no files have been summarized (and the GUI's "empty"), it's still possible to export a CSV of "nothing." Ideally, the "Export" button should be inactive in this case.

Solution

If nothing's been summarized, then "grey out" the "Export" button.

Add Logging

Issue

Debugging errors is difficult because there's little in the way of log output.

Solution

Add logging for the standard log levels. For bonus points, colorize by log level:

• DEBUG -- Grey: #333333
• INFO -- Cyan: #009ce0
• WARNING -- Yellow: #fcdc00
• ERROR -- Red: #f44e3b
• CRITICAL -- White text with red background: #ffffff with #f44e3b

External Product Site

Issue

Since this is a user-focused GUI application, it should have a user-friendly "external site" for new users.

• description of Folsum with screenshots of GUI (preferably animated GIFs that illustrate usage)
• platform-specific "download" button for latest release
• "new releases" announcement at top of page

Auto-generate Documentation

Issue

Contributors would appreciate auto-generated HTML documentation that shows information about FolSum's (internal) API and how things are laid out. This is also a prerequisite for adding a slick crates.io deployment target.

Solution

Add automatic documentation generation to CI/CD pipeline.

Change Repo Language from Javascript to Rust

Issue

The repo's language is auto-detected as Javascript when it's actually a pure-Rust project.

Solution

Ignore docs/, which seems to contain a lot of JS files in other branches.

Updates

• This change was implemented on branch internal/repo_language in commit 1ec2102, but it seems to take a while before the change takes effect.

Separate Thread Concerns: GUI, "main", and "worker"

Issue

Worker threads (for directory summarization and CSV export creation) are spawned from the GUI thread. The GUI thread should not be the parent thread of worker threads.

Solution

Spawn worker threads from (new) "main" thread via the GUI thread, which should be the first thread that the "main" thread spawns. The GUI should call back to a thread pool manager in the "main" thread when spawning worker threads.

Make `README.md` Pretty

Issue

README.md looks a bit stark. It could use:

1. emojis in headers
2. FolSum's logo at the top
3. table of contents
4. branch table: note that dev and others increment minor/patch, not just minor

WASM: "Summarize" Crashes

Issue

The WASM build crashes when you click "Summarize." This is probably because there's no failure case in which no directory to summarize has been defined.

Solution

Make a test case to ensure that WASM builds don't fail when they have nothing to summarize.

Improve Error Handling

Issue

FolSum's leaving it's proof-of-concept stage, but internally its code isn't very resilient to unexpected failures. Due to the project's simplicity, these failures aren't likely to happen, but it's better to .expect the unexpected 🫠.

Solution

Add some slick error raises and catches. For bonus points, do a bit of chaos engineering in the unit tests with failures cases that could happen.