I’m Committing to Better Standards for Underpin

[alexstandiford]

Several years ago, I created a PHP framework called Underpin. At the time, this was created based on my general frustration with needing to copy/paste code between WordPress projects.

The problem is that this project has been written, and re-written, and re-done in it’s entirety as my tastes and understanding of programming architecture has improved. This has made it wildly impractical to make it actually something that is documented properly.

I’ve historically treated this system as my own personal playground, being a place where I can experiment with my personal needs, however I never did a great job of making that fact clear. Unsurprisingly, adoption has never really been a thing with this platform, and honestly that is probably for the better.

Last year, I spent some time working on another open source project of mine, Adiungo. While working on this project, I spent a lot of time making it represent the absolute best I can offer in-terms of open source communication, test-driven development, and documentation practices. I’ve learned a lot since working on that project, and want to bring that level of commitment to Underpin. This is especially important since Adiungo actually depends on Underpin, which means that, by proxy, anyone using Adiungo will also be using Underpin!

Stabilize the Codebase

After using Underpin for a few years, I’ve really come to find specific patterns in what I use, as well as many things that I don’t use, and I think that documenting these key patterns will help to codify what needs to exist in Underpin. I believe this can be a key factor in giving me what is needed to be able to make this a stable toolkit that I can use, as well as anyone else on the web.

Library, or Framework? Let’s Both It

I think the biggest problem I’m having with Underpin is that I continue to oscillate between it being a library, and a framework. As a result, the opinionated, or un-opinionated nature of the core repository fluctuates over-time.

I think the solution is to break the Core repository into two separate things. One being the true “core” plugin, which contains nothing but the library, including the helper classes, registries, and other things that don’t really impact the architecture of whatever you’re building, just make things generally easier.

I want to explore this because there are many personal projects I’ve worked on that absolutely does not use Underpin as a framework. Usually, it just uses a few core features, like registries or URLs. Most projects simply don’t need a full-blown framework, or what I build doesn’t really align with the nature of the framework itself.

Further, I think the “framework” portion is a lot harder to figure out how to do well, and I think it’s the part that results in most of the major changes in Underpin. I’d like to isolate that from the really useful bits that I use every day. It might even just go away entirely, but I want to at least extract all of that into a repository juuuust in-case I run into a situation where I (or someone else) needs it.

Proper Documentation

The biggest problem I have with Underpin today is that it has absolutely no documentation. Like, anywhere.

This is because of the transformative nature like I described above. It’s kind-of an issue because as I work with this system more, I have to spend a lot of time explaining how things work to other people instead of simply linking to documentation that has been thought through and written well.

Obviously, this is going to make it hard for other people to actually adopt Underpin, too. I wouldn’t adopt something that has shifted as much as Underpin, and I definitely wouldn’t if there wasn’t any documentation. Red flags abound!

I think now that I have been using it for a while and have a deep understanding of what is good, and what are big helpers for my approach to programming, that it’s time to take the time to actually explain how everything works. This also plays really well with stabilizing the codebase as I mentioned above. A lot of the decisions on what’s “library” vs “framework” can be existential, and sometimes the best way to figure out where something needs to go comes from writing the docs.

It ‘aint much today, but I did finally get around to making the actual documentation site, as well as the repository. This will allow me to start actually adding content to the docs site, and was a big blocker that I’ve managed to get out of the way. That feels solid.

Better Merge Processes & Releases

Another thing that I really like about how Adiungo is set up, is that it has a lot of the essentials that makes contributing to an open source project possible. Things like:

• Merge PR & Issue Templates
• CI and Automations
• Coding standards, PHPCS, and PHPStan

This isn’t ready yet, mostly because I can’t really do these things until I get the core code separated from the framework code, but once that’s done I can start adding these things. I think they will have a profound impact on how Underpin is updated, will help keep pull requests small, and also make releases smaller, more-frequent, and allow this repository to upgrade in small pieces. This will allow people to make the changes needed to their sites to support changes and updates.

Conclusion

Historically, I’ve taken a lot of shortcuts with setting up, and using Underpin. I feel that it has largely been a disservice to the open source community, and I want to make the changes needed to rectify this. I want to make Underpin something that I can share with others better, and something that others feel comfortable with using. And that starts with taking ownership of the code, stabilizing it, and documenting it.

It won’t happen overnight, but it’ll come in-time.