⭐ Building cool software projects

How to make good programming (specially open source) projects?

I don't claim to be an expert, but I think I have accumulated a fair amound of experience.

Here I collect best practices, or at least the ones I liked.

Table of Contents

related project

. projectopensource

. project

[A] * clearly state the purpose project

[2019-06-13] joeyates/imap-backup: Backup GMail (or other IMAP) accounts to disk project

Design Goals

it's good to state design goals

[A] * compare with similar projects project

Often there are multiple projects that do the same thing, and it's nice to know why you should prefer one over another.

[B] [2019-08-18] "why not use…" section link in attrs project

[B] [2020-03-01] provide comparison with other similar projects project

[B] * demos projectdemo

  • it's nice if you can provide a web-based demo that doesn't require any installation.
  • perhaps the next worst thing is something like a Docker container – you can safely try it knowing you won't mess up your OS
    It also basically means 'reproducible build', and easer testing.

TODO [A] [2020-12-07] VisiData in 60 Seconds | Hacker News projectdemo

Wow, the project homepage has a great dynamic command-line generator that lets you specify what you are trying to do.
This may exist elsewhere, but it's the first time I've seen it and I hope to see it on more projects!

STRT [B] [2019-12-27] Getting started — Datasette documentation projectdemo

Try Datasette without installing anything using Glitch
Glitch is a free online tool for building web apps directly from your web browser. You can use Glitch to try out Datasette without needing to install any software on your own computer.

TODO [C] [2021-03-05] do for HPI projectdemohpi

[B] [2020-05-22] Using SQL to find my best photo of a pelican according to Apple Photos | Hacker News projectdemohpipublish

apparently people like specific demos

[B] [2020-06-06] 'Example interaction' section projectdemo

Example interaction: Install pipx with pip: pip install --user pipx

STRT [B] Demos are important! projectdemo

CREATED: [2019-12-11]
Link to the actual repo:
As others said, I recommend adding a GitHub pages of a demo or something. Not fun having to spin this up yourself to test what it does/looks like.

[C] [2019-11-21] cybersemics/em: 🖋A multi-hierarchical mind-mapping app for personal sensemaking. projectdemoselfhosted

Localhost can be tunneled to a public url for mobile testing purposes using ngrok.

need to figure out how to quickly selfhost stuff

[B] * configuration projectconfigs

[A] try to use as many reasonable defaults as possible projectconfigssoftware

CREATED: [2020-05-24]

Seems that people hate complicated configuration

  • $HOME for configs/paths/cache (e.g. XDG-compliant, something like appdirs)

[B] "configs suck" think how malleable your config needs to be projectconfigs

[C] [2021-02-13] Database Configuration | InfluxData Documentation Archive projectconfigs

Controls the availability of the built-in, web-based admin interface.
    Note: The Admin UI is deprecated as of InfluxDB 1.2.
enabled = false
Set to true to enable the admin interface.

Environment variable: INFLUXDB_ADMIN_ENABLED

I guess it's a good pattern?
e.g. split env variable by _ and bind to code

[C] [2021-01-09] JupyterLab projectconfigsui

good setting design with system defaults (readonly) and user preferences on the side

[B] * documentation projectdocumentation

Documentation is frustrating because it usually requires you to document what you already know, it's usually also duplicates tests, docstrings etc.

[B] related: literate programming projectdocumentationliterate

[C] [2020-05-05] High-level overview (Mu4e 1.4 user manual) projectdocumentationsoftware

| emacs   |
|    +------+
+----| mu4e | --> send mail (smtpmail)
      |  A
      V  |  ---/ search, view, move mail
+---------+    \
|   mu    |
  |    A
  V    |
| Maildir |  <--- receive mail (fetchmail,
+---------+                     offlineimap, ...)

characters (e.g. A, V) can be used for drawing

[C] [2020-04-21] inspiration: Create Agent - Huginn projectdocumentation

Huginn is nice, when you try to create 'agent' it shows the documentation/examples aside

[B] * collaborating project

How to make the project more welcome to contributions?

[A] [2020-05-04] make sure it's very easy to contribute project

  • use CI
  • specify how to run tests (usually clear from CI coffig)
  • specify how to spin up the developer environment (e.g. editable install)

TODO . projecthpi

TODO . projectpromnesia

[C] * screencasting projectscreencast

I found screencasting to be pretty finicky.
Especially when you want to automate things, e.g. like I did with short demos for promnesia.
(see – it's extremely hacky and not sure how to make it generic)

TODO [B] [2019-12-10] GitHub - asciinema/asciinema: Terminal session recorder 📹 /r/coolgithubprojects projectscreencastcli

[B] [2020-03-25] screenkey program to display keypresses projectscreencast

[C] [2020-04-02] Capture/Desktop – FFmpeg projectscreencast

[C] [2019-10-11] Weekly /r/Orgmode Open Discussion - October 11, 2019 /r/orgmode – gif screencasting tool projectscreencastemacs

That looks really cool.  Note that many users don't know what CFEngine is, so you might want to mention that (then again, maybe users who don't already know what it is don't matter, haha).
Your demo GIF is pretty cool.  You might find this interesting: after recording and tidying up demo GIFs for `helm-org-ql` several times, I wrote a shell script to make it easier.  Using the `gif-screencast` package for Emacs, all I have to do is run the script, make the Emacs window active, and it does the rest.

[C] [2020-01-27] gif-screencast 1.1 is out /r/emacs projectscreencastemacs

I'm happy to announce the release gif-screencast 1.1!

It isn't much, but I know that gif-screencast has had annoying issues for a
while, I figured I'd rather let the community know!

- Fix off-by-one error in frame delay (thanks to /u/alphapapa for this one!)
- Remove "Press ... to stop" message from resulting GIF.
- New `gif-screencast-start-or-stop` command.
- Log the complete command lines of all invokes commands.

[C] [2020-05-04] Terminal Recorders: A Comprehensive Guide projectscreencastcli

[C] [2020-04-02] phw/peek: Simple animated GIF screen recorder with an easy to use interface projectscreencast

Peek does not support this natively. But you could install an external tool like key-mon which is usually included in most distributions, so you can easily install with your package manager. Then start key-mon with key-mon --visible_click. The --visible_click option is for drawing small circles around mouse clicks.
  • [2020-04-02] looked at peek for demo automation, and it doesn't quite do the trick
    • you can continue/pause recording from the console
    • you can't set window id/adjust (granted, you can do it externally via xdotool which is arguably more modular)
    • you can't set recording format/path from the console (and even save the video?)
      that made it useless for my purposes

TODO [D] [2019-09-10] Input Overlay | OBS Forums projectscreencastdemo

A small plugin for obs studio that shows keyboard, mouse and gamepad inputs on stream.
Supports Windows and Linux (64bit, if you need 32bit either compile it yourself or message me)

[D] [2020-04-02] recordmyscreen projectscreencast

I think it dumps broken ogv file. There is some jerkiness.
When you convert it to something else with ffmpeg, it's complaining about broken frames and sometimes even segfaults

also it hasn't been updated for a decade, apparently

[C] * landing page project

Often "langing pages" for startups are bloated and very infromation sparse.
For open source projects it's usually better though (especially considering readme is usually enough!).
Here I'll collect the ones I liked.

[C] [2020-05-27] inspiration: Fraidycat project

nice design and summary on this page

TODO [2021-03-05] could do similar for promnesia projectpromnesia

[C] * licensing projectlicense

[B] [2019-12-30] Choosing a license for GoatCounter projectlicense

GPL (any version)
Bad: doesn’t have the “network protection”: you don’t need to submit changes back to me if you modify the code and run it only as a SaaS.

TODO [C] [2019-10-12] Licenses – projectlicense

GNU GPL v1, v2, v3

TODO [C] [2019-10-12] Licenses – projectlicense

The following steps are required in order to be able to take advantage of the reduced requirements:
    The LGPL-licensed library must be used as a shared library (dynamically-linked).
    For LGPL v3 only, the user must be able to replace the shared library with a compatible library and have it work (the user must be able to swap out libraries on the device).
    Customers must receive either object files or source code (including any modifications) of the LGPL-licensed library.

[C] projectlicense

[C] [2019-12-11] Create LICENSE by MitchTalmadge · Pull Request #10 · kootenpv/gittyleaks projectlicense

If you are the copyright holder, it's up to you how you license your work —I think the only catch is that you can't retrospectively revoke open-source licenses for previous versions, but I think you could easily publish an updated version with a different license, or even license with two different licenses if you wanted to. Also, if others have previously contributed to the project whilst it was under a given license, you will need their permission to relicense it, unless you have a copyright-grant agreement with them (such that they assign copyright to their contributions to you).

[C] * naming project

It's annoying to have to come up with name when the project is ready and you are keen to release it.

  • my personal strategy is thinking and having short brainstoming sessions now and then and writing down ideas
    Then after some time I just pick the one I like most.
  • use thesaurus to find synonyms
  • make sure it's unique enough, search for existing projects with the same name

[D] * versioning project

[B] [2020-01-02] for end user software (i.e. not 'libraries'), calendar versioning is more useful than semantic project

[B] ok, definitely should keep changelog in the repository file (and then link to headings), instead of github native interface project

CREATED: [2020-12-05]

The reason is to avoid siloing the changelog on Github. It's fine to also copy it on "Releases" page as well, but make the (or any other plaintext file) the primary source of truth.

---------------------------------- project

STRT [B] [2020-01-19] How do you stay inline with your vision on long term projects? | Lobsters project

STRT [C] [2019-06-30] Ask HN: How do you come up with new project ideas? | Hacker News project

[2019-07-23] "A vague mental checklist I've been accumulating" project

  • Why didn't I stick with my last idea?
  • Could I make that idea simpler?
  • Could I reuse that idea elsewhere?
  • Why am I not motivated to work on this idea (any more)?
  • Could I change it around so that I am?
  • What are people looking for?
  • What are people NOT looking for?
  • What ideas are already floating out there, that haven't been popularized, but could be done better?
  • What ideas are getting too much hype and attention, so that I can filter them out?
  • Is my idea trivial enough not to scare me?

TODO [C] [2020-06-05] share donation links in readme between my projects project

I don't need money myself, but would be nice to 'reroute' donations to the libraries I use, or tool that lets me build the projects.

[D] [2020-02-27] tools that only take stdin/stdout are a bit horrible to debug (no io to gdb) projectdebugcli

---------------------------------- project

TODO [C] [2021-03-05] Open source projects should run office hours | Hacker News projectprojects

TODO [B] [2021-03-15] Thomas Strömberg on Twitter: "An uncomfortable truth that open-source projects struggle with:👇 Improvements to your onboarding docs generate 10X the ROI vs improvements to your codebase 🔖 Great documentation creates a virtuous cycle of adoption, contributor diversity, and success.♻️" / Twitter projectprojects

An uncomfortable truth that open-source projects struggle with:
Improvements to your onboarding docs generate 10X the ROI vs improvements to your codebase
Great documentation creates a virtuous cycle of adoption, contributor diversity, and success.
Jump to search, settings & sitemap