Skip to content

DispatchesΒΆ

Please Format Your Code Blocks: GitHub Issue Etiquette

You are a maintainer. You have carved out thirty minutes between meetings to work through the open issues on your project. You open the first one. The title is promising. The reporter clearly hit a real bug. And then you see it: a wall of unformatted YAML, raw Terraform, and shell output, all smooshed together into a single paragraph, every newline stripped, every indentation gone, triple-quoted strings collapsed into nothing, angle brackets eaten by the Markdown renderer. You cannot tell where the config ends and the error begins.

You close the tab.

If you are a maintainer, you have lived that moment.

If you are a contributor, please keep reading, because this post is for you, and it will help your issues get more attention.

DCO vs CLA: Managing Contribution Agreements in Open Source

When you accept code contributions to an open-source project, you are entering a legal relationship with every contributor. Who owns the code? Do you have the right to relicense it? What happens if a contributor later claims you do not have permission to use their work? Two mechanisms exist to answer those questions before they become problems: the Contributor License Agreement (CLA) and the Developer Certificate of Origin (DCO).

This post takes a thorough look at both: what they are, how they work, the tradeoffs involved, and the tooling available to automate enforcement on GitHub.

Why I Use JetBrains GoLand and PyCharm Over VS Code

VS Code is a remarkable editor. It is fast, extensible, and free, and it has become the default tool for an enormous portion of the developer community. I use it myself for PowerShell, general Markdown, and lightweight editing. But when I sit down to write Go or Python, GoLand and PyCharm are where I do my best work.

This is not a condemnation of VS Code. It is an explanation of why, for language-specific work, purpose-built IDEs make me a more productive and deliberate developer.

Light and Dark Mode Images in GitHub Markdown

GitHub renders Markdown with either a light or dark theme depending on the user's system or GitHub appearance settings. A logo or diagram that looks sharp on a white background can disappear entirely when the same user switches to dark mode. GitHub provides two ways to serve the correct image for each theme without JavaScript.

If you are using MkDocs Material, the same problem has a pure-Markdown solution covered in a companion post: Light and Dark Mode Images in MkDocs Material.