→ node [[projects]]

Current Projects

Backlog

Older Projects & Events

Table of Contents

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.

related

. [[opensource]]

. [[social]]

* clearly state the purpose

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

Design Goals

it's good to state design goals

* compare with similar projects

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

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

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

* demos [[demo]]

  • 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.

[2020-12-07] VisiData in 60 Seconds | Hacker News [[project]]

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! https://www.visidata.org/

[2019-12-27] Getting started — Datasette documentation [[demo]]

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.

[2021-03-05] do for HPI [[hpi]]

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

apparently people like specific demos

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

[2020-01-16] ngrok - secure introspectable tunnels to localhost

Demos are important! [[project]]

Link to the actual repo: https://github.com/hellojoshuatonga/react-use-fuzzy
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.

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

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

need to figure out how to quickly selfhost stuff

* configuration [[configs]]

try to use as many reasonable defaults as possible [[project]] [[software]]

Seems that people hate complicated configuration

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

"configs suck" think how malleable your config needs to be

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

[admin]
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

[2021-01-09] JupyterLab [[ui]]

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

* documentation [[documentation]]

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

related: literate programming [[literate]]

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

+---+
| 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

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

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

* collaborating

How to make the project more welcome to contributions?

[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)

. [[hpi]]

. [[promnesia]]

[2020-06-06] Add a “contrib” directory to your projects | Drew DeVault’s Blog [[project]]

* screencasting [[screencast]]

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 demos.py – it's extremely hacky and not sure how to make it generic)

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

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

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

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

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.

https://github.com/alphapapa/org-ql/blob/master/images/demo-helm-org-ql.sh

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

I'm happy to announce the release gif-screencast 1.1!
https://gitlab.com/ambrevar/emacs-gif-screencast

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.

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

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

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

[2019-09-10] Input Overlay | OBS Forums https://obsproject.com/forum/resources/input-overlay.552/ [[screencast]] [[demo]]

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)

[2020-04-02] recordmyscreen

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

* landing page

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.

[2020-05-27] inspiration: Fraidycat

nice design and summary on this page

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

* licensing [[license]]

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

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.

[2019-10-12] Licenses – opensource.google.com

GNU GPL v1, v2, v3

[2019-10-12] Licenses – opensource.google.com

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.

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

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).

* naming

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

[2019-09-17] Find words containing these letters in sequence

[2020-01-02] Open source project name checker - OSPNC

[2019-12-23] Show HN: Generate names like snapchat, dropbox, paypal for your next project

https://namewink.com/

* versioning

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

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

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 CHANGELOG.md (or any other plaintext file) the primary source of truth.

----

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

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

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

  • 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?

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

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.

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

----

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

[2021-03-15] pull">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 [[projects]]

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.
⥅ pulled node [[public-utility]]

public utility

⟴ stoa (shared document) at doc.anagora.org/projects
⥱ context
⥅ context node [[2005]] (empty)
⥅ context node [[2005]] (empty)
⥅ context node [[2006]] (empty)
⥅ context node [[2007]] (empty)
⥅ context node [[2007]] (empty)
⥅ context node [[2007]] (empty)
⥅ context node [[2008]] (empty)
⥅ context node [[2009]] (empty)
⥅ context node [[2010]] (empty)
⥅ context node [[2012]] (empty)
⥅ context node [[2014]] (empty)
⥅ context node [[2019]]
⥅ context node [[2020]]
⥅ context node [[2021]] (empty)
⥅ context node [[barcamp]] (empty)
⥅ context node [[barcampamsterdam]] (empty)
⥅ context node [[barcampbrussels]] (empty)
⥅ context node [[barcampvancouver]] (empty)
⥅ context node [[berlin-open-source-salon]] (empty)
⥅ context node [[cli]]
⥅ context node [[cobuilding]]
⥅ context node [[community-isp]] (empty)
⥅ context node [[configs]] (empty)
⥅ context node [[configs]] (empty)
⥅ context node [[configs]] (empty)
⥅ context node [[configs]] (empty)
⥅ context node [[connecting-to-the-agora]]
⥅ context node [[custom-bags-in-vancouver]]
⥅ context node [[debug]] (empty)
⥅ context node [[debug]] (empty)
⥅ context node [[demo]] (empty)
⥅ context node [[demo]] (empty)
⥅ context node [[demo]] (empty)
⥅ context node [[demo]] (empty)
⥅ context node [[demo]] (empty)
⥅ context node [[demo]] (empty)
⥅ context node [[democamp-vancouver]] (empty)
⥅ context node [[documentation]] (empty)
⥅ context node [[documentation]] (empty)
⥅ context node [[drupal-association]] (empty)
⥅ context node [[emacs]]
⥅ context node [[hpi]]
⥅ context node [[license]] (empty)
⥅ context node [[license]] (empty)
⥅ context node [[literate]]
⥅ context node [[moa-party]]
⥅ context node [[northern-voice]] (empty)
⥅ context node [[open-angel-canada]] (empty)
⥅ context node [[opensource]] (empty)
⥅ context node [[opensource]] (empty)
⥅ context node [[pixelcrafters]] (empty)
⥅ context node [[polyglot-conference]] (empty)
⥅ context node [[project]]
⥅ context node [[projects]]
⥅ context node [[promnesia]]
⥅ context node [[publish]] (empty)
⥅ context node [[publish]] (empty)
⥅ context node [[screencast]] (empty)
⥅ context node [[screencast]] (empty)
⥅ context node [[screencast]] (empty)
⥅ context node [[screencast]] (empty)
⥅ context node [[selfhosted]] (empty)
⥅ context node [[selfhosted]] (empty)
⥅ context node [[ship-ip-not-product]] (empty)
⥅ context node [[social]]
⥅ context node [[software]]
⥅ context node [[startupweek-vancouver]] (empty)
⥅ context node [[ui]] (empty)
⥅ context node [[ui]] (empty)
⥅ context node [[vancouver]]
⥅ context node [[vancouver-local-makers-directory]]
⥅ context node [[venture-scouts]] (empty)
⥅ context node [[weareyvr]] (empty)