RFC: Refactor for maintainability (Roadmap to 1.0)

[mroth]

Over a decade has passed since scmpuff was originally written (it was written in Go version 1.3!). Originally intended to be a quick hack to redo the core text parsing of scmbreeze in Go to address performance issues and (my perception of) feature bloat, it has become more of a standalone app used by many. Since then, the state of the art has progressed substantially, not to mention I'm a fairly significantly less terrible software engineer.

In current state, scmpuff is difficult to maintain. Refactor to make a more modern application that can be more easily maintained by the OSS community, as well as introduce best practices.

In some ways, this can be thought of a roadmap to v1.0.

Note

This is a quick brain dump and has not been polished into an actual written document yet. Nonetheless, since I don't have much time to dedicate to this project currently, I'm sharing the rough status of the notes publicly and hope to encourage participation, since this effort will almost certainly be "help wanted."

Major tasks

• Structure: Update project structure to current best practices, separating out internal packages from CLI mechanisms.
• Tooling(Language): Move build infrastructure to go1.24 and adopt language niceness we can take advantage of.
• Tooling(Integration tests): The Aruba based integration testing has provided fairly unparalleled flexibility in testing across multiple shells. However, the Ruby based toolchain for doing so is inconvenient for Go developers. It's a poorly kept secret that I developed a Go based replacement for Aruba called jeju, which also brought in better filesystem isolation and concurrency and a bunch of other nice stuff, but I unfortunately never had time to get it past the ~70% mark, and I don't have time to return to developing this currently. Perhaps some day, but in the interim, testscript seems to be the best alternative and what the Go community uses. I would need to investigate its isolation and concurrency ability, but my proposal would be to port the entirity of the integration suite here to it if feasible.
• Git plumbing: The original git status --porcelain parsing was a port from scmbreeze, and moving to parsing git status --branch -z brought better consistency, but there are still a slew of edge cases built up over the years that need to be handled, and some pathological edge cases that haven't been fully tracked down. A top priority should be migration to using go-git for reading repository information. This is another place I have test code, I think it should be fairly straightforward. (Another option would be to write a parser for --porcelain=v2 supported by more recent versions of git, which addresses many of the warts from v1).
• Cross platform: The ANSI colors should be replaced with a modern color library for improved cross-platform suppport.
• Documentation: Automate the very manual building of the of the demo animated gif for the website so it can stay up to date. I have done some tests with charmbracelet/vhs and it looks very promising.
• Naming: scmpuff was a play on scmbreeze, but this is its own thing now, and the name never was obvious to people. Rename the project and tool to something descriptive, e.g. git-numbers. This is a non-trivial task due to documentation, and integration with various package managers around the world, but should be a pre-requisite for a v1.0.

Edge ideas

• I have some thoughts as to how shell integration could be removed entirely, instead relying on wrapper commands (e.g. git numbers [add|rm|etc]), with index state being stored on the filesystem vs in environment variables. This would be a breaking change, but would grant immediate compatibility with 100% of shells. This is how I would architect things if starting today, but is likely more of a v2.0 idea given the drastic nature of the change.

[Tobbe]

As a long-time scm_breeze user, I just found this repo. And as I was browsing around to try to get a feel for things I found this issue. It says

A top priority should be migration to using go-git for reading repository information

Given the recent update in #33 I wondered if that was still the direction you wanted to take, or if that statement should be updated to instead point towards your porcelain parsing library.