strugee.net

Have you ever submitted a Pull Request and had the maintainer give you feedback that says something is wrong? This is of course, perfectly natural, and is why we do Pull Request reviews in the first place. But have you ever thought it was actually the maintainer doing the review who was wrong?

I'm the maintainer of a number of open source/free software projects and I have a message for you: tell this to the maintainer, even if you're new, even if you feel like you have no idea what you're doing.

I'm sure to some people more experienced this sounds like obvious advice, but when you're new to this stuff getting feedback can be really scary. Maintainers have often spent years in the free software community and are super comfortable with how things work, not to mention that they might be more experienced in the language or framework their project uses. So it's super easy to just take their word as gospel. But I think it's super important to remember that everyone's human just like everyone else, and everyone has something to learn.

As a concrete example, take this comment on a Pull Request I received. If you read it and the following comment, I seem like an expert on eval(), but what you don't see until you read all the way to the bottom is that I spent about 20 minutes composing that comment because I had to double-check MDN to make sure I was actually correct. And honestly, that was great. That Pull Request forced me to recheck what I thought about the way eval() worked, and the contributor learned from it too! So it ended up being a win-win. Even if I was wrong, that would have been great too, since I would've learned something new. Sometimes the thing being discussed is just a really tough or confusing problem, and getting feedback on a PR can be a really awesome chance for both you and the maintainer to collaborate more closely and figure it out together!

I'm sure this won't work in every community. But honestly, if it doesn't, the maintainer you're running into is probably an ass and not worth bothering with anyway. This is what doing things in the open is all about - freedom 1, after all, is "the freedom to study the source code and make changes", the operative word being "study". The fact that knowledge is shared out in the open with anyone who wants it is one of the most amazing parts of this community, and I want to encourage you to stay curious and ask lots of questions.

So if you've ever walked away from a Pull Request review feeling like something wasn't quite right, consider this your permission slip to politely tell your reviewer you think they're wrong[1] - just make sure to be polite and explain why you think so! And remember, whatever they say, they're not criticizing you personally. I hope you embrace it as an opportunity to grow.

Footnotes:

[1]: Phrasing this as "I think you're wrong" instead of "you're wrong" is great for a lot of reasons, but one notable and less obvious one is that if the maintainer does end up being right, you won't feel silly.

Edited to clarify that I'm not advocating inpoliteness, to change the phrasing to "I think you're wrong", and to add some nice framing around a chance to collaborate on a difficult problem. Thanks to the Recurse Center folks whose feedback turned into these changes, particularly Sumana Harihareswara and Julia Evans.

Last night I officially published pump.io 5.1 to npm as a stable release!

As I wrote in the beta announcement, this release contains a variety of improvements:

• Zero-downtime restarts, which allows administrators to seamlessly roll over to new configurations and codebases
• The daemon now generates startup log warnings on bad configurations, including insecure secret values and internal parameters
• An official Dockerfile is now included with the release
• The logged-out mobile homepage's menu icon is no longer incorrectly styled as black
• An authorization problem with SockJS connections has been fixed

5.1 stable does include one change the beta didn't: a bump to the version of the gm npm package which we depend on. This bump was done as a precautionary measure, as previous versions of gm depended on a version of the debug module which was vulnerable to denial-of-service security bugs.

As a project, we addressed these bugs back in October when we issued security releases for all supported release branches, and at the time we confirmed that the vulnerable function wasn't used by gm. Today's gm bump does not constitute a security release; instead, we're just bumping the version as a precautionary measure in case we missed something in October's assessment of the situation.

Aside from the gm bump, there are (as usual) miscellaneous version bumps included in this release. We've also started tracking test suite coverage information as well as overhauled our documentation on ReadTheDocs, moving most of the in-repository documentation there.

If you want even more details of this release, you can also check out the changelog.

pump 5.1 is a drop-in replacement for 5.0. That means if you're using our recommended installation method and installing from npm, you can upgrade with npm install -g pump.io@5.1. If you have a source-based install, you should merge and/or switch to the v5.1.0 tag. And as always, if you encounter any problems, please feel free to reach out to the community or file bugs you find.

Finally, I would be remiss if I didn't point out that pump.io has a brand-new announcement mailing list! While the blog is great for announcing new releases, not everyone finds it convenient to check. Also, if we issue new betas in the middle of a release cycle, these aren't typically announced on the blog. Therefore in the future all new releases will be announced on the mailing list, not just initial betas. If you want to subscribe to the mailing list, you may do so here - you'll get announcements of new features only, not e.g. feature announcements as seen on this blog. I hope people find this service useful!

This post also appeared on IndieNews.

Last night I hit publish on version 1.0.0 of a new project, lazymention! Whoohoo!

tl;dr: lazymention exists to add Webmention support to static sites!

To elaborate a little bit, I developed lazymention because I had a problem with this site: I wanted to send outbound Webmentions when I link to things, but my website is completely static. (Webmention, in case you didn't know, is a way to notify another website that you linked to them, so the other website can display some UI about your reply or whatever.) The page builds happen on my local machine, not on the server. One option would be to just send Webmentions from my local machine too, but this isn't really a good solution for a couple reasons. First, I couldn't do it automatically at build-time because the built pages wouldn't have been deployed to the server yet, so receivers of my Webmentions would reject the mentions due to the source being nonexistant. That meant that I would have to have a separate step, which wouldn't really be that big of a deal (lazymention requires pinging a server too) except for the second reason: I would need some way to keep track of where I'd already sent Webmentions to, and that would require synchronizing across computers. Probably the only decent way to do that would be to check it into Git, but having a program's data store checked in right next to the source code just feels kinda ugly. Plus, then it can't be shared with other people as a service.

So instead of doing it locally, I elected to build a server instead. Here's how it works: you mark up your stuff with h-feed and h-entry, and whenever anything happens (e.g. you publish a new blog post or whatever), you ping lazymention with the URL (either the feed or the post itself). lazymention will use your microformats2 markup to find the canonical location for a given post, then it will find all the links in the post and send Webmentions for them. And presto! You've just sent Webmentions for your blog. lazymention also records when it's sent mentions, so if you ping it again, nothing will happen unless you've updated your content. I'm also planning to add WebSub support to lazymention, too, and that'll work in the exact same way.

lazymention is super easy to get started with, especially because I've provided thorough documentation in the README. If you find anything that's confusing or missing, please let me know by filing an issue! I'd love to get it fixed. In fact, I'd be thrilled to hear about both positive and negative installation experiences.

Oh, and one more thing - lazymention is reusable in other applications. If you're writing a Node.js app and want to reuse its HTTP API, you can use its embedding API to get at the Express application and Router used internally. I'm not sure if people will actually find this useful, but I wrote it just for kicks anyway. See the embedding documentation for more!

Cheers, and happy mentioning! Elegant outbound Webmention for static sites is here.

While I was at the Recurse Center, I came up with an interesting theory, and today I thought I'd finally formally write about it on my blog. Here it is: shell script is one of the purest forms of human expression, at least as far as technology is concerned.

Why? Well, shell script is this weird mix of actual programming language things and macro expansions, and even the programming things tend to be... odd, to put it politely. As a trivial example, did you know that this:

$ echo {1..10}

results in this output:

1 2 3 4 5 6 7 8 9 10

Shell scripts[1] know how to expand number sequences; it's just built-in to them. Variables work with substitution too, and you can even build commands with them:

PAGER=less
$PAGER longfile.txt

The key thing to note here is that the second line is replacing $PAGER with the literal text less, and then running the resulting command line. The "variable access" is basically just an inline macro expansion, and the shell doesn't really handle it very intelligently. (This is also why you often need to quote variables when you access them - if they have whitespace in them, the shell will interpret the variable as more than one word.)

Or take the type system of the shell: it has none[2]. For example, what does 0 mean? It could represent any one of these things:

1. The number 0
2. The string "0"
3. A binary we're invoking (well, trying to invoke) called 0
4. An argument to a binary
5. File descriptor 0 (stdin)
6. A file named 0

All of these things combine to make the shell incredibly flexible and powerful - you can often express a lot in shell script with very little characters by writing "macros" in the right way.

It's also what makes shell such a god-awful programming language.

Think about it - as programmers, much of what we do seeks to impose order on our systems. We lint our code and run it through style checkers. I personally like to turn up my linter settings to maximum. And we use the concept of types to help organize our code - sure, there's disagreement on how much order types should impose, but we all pretty much agree that there should be some concept of types and type safety. Hell, for the languages whose type systems are basically "wtf are types", we make tools to impose additional safety on top of that - take TypeScript and Flow, for example. We also love to (hate to) write tests to ensure that our code fulfills some interface or behavior contract. (Even the idea of an interface seeks to organize and compartmentalize complexity in the system.)

Humans are inherently messy. We're scatterbrained and easily distracted, and our thoughts (or at least, my thoughts) tend to jump all over the place. Shell script is an amazing way to express your ideas because it lets you get directly to the goal so quickly, in a way that matches that messiness that defines us as a species. But since so much of our work as programmers is about trying to counteract our messiness, shell script is a terrible way to write real programs, for the exact. Same. Reason.

Footnotes:

[1]: Those written in bash, at least.

[2]: Note that this is different from having a type system of "wtf are types?? wat" - JavaScript is a good example of a language with such a type system, as is (to my understanding) PHP. The shell, on the other hand, has no type system at all.

So I just wanted to write something up real fast to document my development priorities over my upcoming winter break (which starts tomorrow, whoohoo!). This is just generally useful to have, because I'm forgetful, but will also help keep me accountable since the list is public.

So, here are the projects I want to get done, in rough order of priority:

1. Polish up an outstanding Node.js Pull Request that automatically generates manpages for every module shipped with Node core
2. Deal with GPG key signing which I have been procrasinating on for, well, years now
3. Push some Debian packaging work forward (I've done some work to get the Profanity packaging up-to-date, and I want to get filter-other-days into Debian as well)
4. Finish up v1 of lazymention - high-priority since it's so close to being done!
5. Finally push through and implement ActivityPub in pump.io core
6. Clear the backlog of PRs sent to pump.io

I also am setting a goal of writing at least two blog posts per week, and I want to try to get some editing done on a paper I'm planning to try to get published (though I'm not sure if I'll end up doing this, honestly).

That seems like a lot, honestly, and yet I feel like I must have missed something - I will update this list if I think of anything else!

Cheers, and happy holidays everyone! \o/