A cartoon depiction of the author, wearing a hoodie and smiling motd.co

Postmarks One-Month Update

First Month Review #

I announced Postmarks publicly a month ago and got a much bigger response than I was ever prepared for. Thank you to everyone who's sent in bug reports or feedback, contributed code to the project Github repo, and spun up instances of their own. I'm still blown away by the reception I received, and the progress the fediverse community has made in helping me move things forward in just one month has been incredible–all while being patient and kind with both my hacky leftover prototype code and my limited availability.

I'm still working full-time at a day job with its own demands, so I'm having to find time for this work around the edges of my responsibilities to work and family (and a big thanks to everyone in my life who's been patient with me in this past month!) That said, I'm still very excited to continue working on Postmarks and help it get to the place where it can be safe, useful, and easy to use for more people than it currently is.

New Features #

note: I didn't work on any of the things listed here; all my contributions this month were bugfixes & "glue work". For more information about who did what, check the changelog at the bottom of this section.

"Tag intersection" browsing #

You can now filter lists of bookmarks not just by individual tags, but by combination of tags. You can either edit the URLs directly and just separate them by slashes:

Or you can click on the small "+" next to any tag you see in a listed bookmark while looking at the list of bookmarks for a particular tag or set of tags.

SQLite, our database engine, actually has built-in full text search, so there's now a "Search" link in the main site navigation at the top and bottom of every page. You can search any substring in the title, description, URL, or tags of a bookmark and see the list of results.

CSV export #

You can now download your bookmarks as a .csv file! CSV import will be coming soon, using the same format to begin with. We may be able to offer import from other formats so that you can pull data in from other bookmarking services eventually.

Improved UI #

The site has been given a subtle but much appreciated upgrade to both its HTML and CSS structure and now does things like "handle narrow aspect ratios" (like, uh, smartphones). There are more enhancements coming to help you customize your install and make it look the way you want, but this gets most of the most annoying problems out of the way. It may be a more challenging git merge for anyone who's forked the project and customized it themselves, but we hope that with the upcoming customization features you won't have to worry about that too many more times.

Temporary repo governance #

Since I've seen initial interest in contributing from a number of people I decided to go ahead and give "collaborator" access to a handful of people who consented to it. We discussed in advance the idea that while I have no immediate plans to change anything, I consider this a non-permanent measure and I reserve the right to "reset" access at any point up to and including a move from my personal account to a full "Github organization".

Adding collaborators gives people the ability to create branches on the repo itself, which makes it easier for us to collaborate on PRs, and when it comes to bugfixes, they have the ability to review & approve each others' PRs. It also lets me create a "Github Project", similar to Trello or other project planning tools, and give those people access to tools that will hopefully help me communicate my priorities and thinking about the growing number of issues that are being filed on the project.

Complete changelog #

Here's what changed this month. If you read below you'll see that I eventually do plan to move to a more standard semantic-versioned release model, which will come with a changelog and so forth, but I wanted to highlight all the fantastic work that got done from the community of people who have been helping so far.

What's Next #

Upcoming Features #

Onboarding/setup flow #

The current setup process for Postmarks is pretty simple but has a few annoying bits that require you to read the instructions carefully and cause some problems if you don't interpret the wording perfectly. We'll move more things into the web admin interface with an onboarding flow that's more like a (much shorter version of an) install of hosted software like Wordpress or Mastodon.

Admin section site customizations #

There's some architectural work in progress right now that will make it easier to manage things like your site title, Fediverse actor name, avatar, and things like custom colors via the web interface. We'll also have a field where you can specify a separate CSS filename to include on all pages, which we hope will make it easier for you to customize the site more fully without worrying about Postmarks software upgrades overriding your changes. (If you're interested in how this is going to work, see the Backend Changes section below)

Network page fixes #

The "network" page, where you can follow other Postmarks instances or accounts elsewhere on the Fediverse, was kind of rushed out at the last second before launch so that I could consider the site to have a prototype of most of the major features I had in mind for the project. It's... pretty broken right now, though, and I doubt it's very useful in its current form. I'm going to spend some time cleaning up the way it detects links in the posts that your instance is able to find as a baseline, but I think we'll have plenty more to do even after that.

Miscellaneous improvements #

There are some other rough edges that I'd like to get some attention on in the short term, including making it easier & faster to discover how to follow a Postmarks instance using both ActivityPub (and Mastodon in particular) and the RSS (technically Atom, but any modern RSS reader should support it) feed.

Project Management #

note: if you're not interested in software development, you can probably feel free to stop reading at this point! Lots of technical details/jargon will follow, and is mostly meant to be of use to people who are keeping an eye on the active development of the software in particular.

Versioning #

I plan to release a new version in October that I'll bump to v0.2.0 to recognize the work that's happened so far. I would like to explore some kind of automation (via Github Actions?) for this, but at the very least will document my process so it can be automated at some point in the future.

When I do this, I would also like to provide a shell script that manages setting up a git remote pointing to the official repo & pulling down the latest released version, letting you override that remote to a fork via an ENV var if you've made your own changes that need to be included.

Once we're on the versioning train I'll follow a loose semver-like structure. I'm reserving the right to update the version to 1.0 at a future time not because of any breaking changes, but just to recognize the state of the software as being "ready" for a wider audience and to celebrate the work that has gone into getting it there. I would consider a release to be ready for 1.0 when it accomplishes all of the following:

CONTRIBUTING.MD & associated documents #

This falls into the "I didn't think there was a rush" bucket of tasks, but after being surprised to see a number of brave folks jump in, I know it's something we need to get set up in October. It's also something I need to do myself! I consider my responsibility here to be to provide the following:

My hope is that once the groundwork is laid for this documentation, it'll be easier to update it over time as we gain new tooling or make changes to how things are run.

Backend Changes #

Unified database with key/value store #

Repo collaborator John has outlined a plan for doing some refactoring of the way we store database info that should both simplify the code and also give us better capabilities for ensuring that future changes are able to be applied to existing installs.

John and I have worked together to create a migration path that ports existing data into that new unified database so that any current installs should get seamlessly ported over to the new setup, and he posted a draft of the first step of that process while I've been traveling this week that I am looking forward to reviewing this weekend.

ActivityPub compliance #

We've had a few regression bug reports and also things I hadn't considered (see the AUTHORIZED_FETCH issue on the Github repo). Right now, there aren't a lot of fully-featured guides to making a fully "compliant" app on the Fediverse–there are W3C specs for things like ActivityPub and ActivityStreams, but following them to the letter isn't even necessarily a good idea, given how it can cause problems with interoperability when other platforms have made opinionated choices about how they interpret the specs.

I expect this to be a tricky balance and one we'll be working on improving for some time to come. There's been initial meta-discussion about this in a few different places and I hope to develop a strategy for how we'll move forward on this. I personally have a lot to learn about the specs themselves, other Fediverse platforms, and tooling that's been created to do things like validate compliance.

Wrap-Up #

There's a lot more to say about the project, and I had outlined another few sections, but I think I've said plenty for now. If you have questions you can always open an issue, get in touch with me on Mastodon, or email me directly (my email address is available on my Mastodon profile). Thanks for reading!