Aquiles Carattino logo

Guide on how to open-source projects

First published:

Last Edited:

Number of edits:

This is work in progress. I am still exploring the challenges of organizing such a course

This article is marked as draft. It is not in its final form.

This is meant to be the central place of a future "How-To Open Source " course. The idea of this course was triggered after reviewing Hardware Control on JOSS.

Define Target Audience

The course will be tailored to researchers, scientists, and companies with scientific roots, such as Dispertech .


The reason why someone would follow this course.

Actionable insights for someone who follows the course

What will people be able to do/know after following the course that was not able to do before the course:

Knowledge gap to be addressed

Personal Motivation

Structure Of the Course

  • What does it mean to open-source a project? Focus on Scientific open source packages and tools such as:
    • PyPylon, ODemis <- There's a company behind them
    • ImageJ, CellProfiler <- Bigger projects, now well funded. Check their origins
  • Examples of smaller packages with a following:
  • What about Open Hardware ?
  • Examples of non-open programs:
    • Gadget (Astronomy)
    • Probably epidemiologic modeling
    • I am sure there are plenty more, need to collect feedback
  • What is the goal of open-sourcing? <- You may have different goals!
    • Scientific reproducibility
    • Empowering a community
    • Gaining attention
    • Lowering the maintenance burden <- Is this true? Perhaps from a company perspective?
    • Marketing strategy around a product
    • Open source is a political act
  • Risks associated with open-source
    • Researcher: Scooping of topics
    • Single(indie)-developer: Someone builds a product on your work
    • Company: Giving away resources to competitors
  • The question: Do benefits outweigh the risks?
    • Or how do we mitigate the risks? <- Topic for later, since this is more technical
  • Choosing the tools to open-source: #git has eaten the world. 3 options:
    • Github <- Where everyone hangs out
    • Gitlab <- Can be self-hosted, e.g. by a university or company
    • Bitbucket <- Is integrated with other tools that belong to Atlassian
  • This course is not an introduction to Git! <- Can I assume people already know git?
  • Readme! Create a description of the project, what it does, how it can be installed. Also, important, how to reach out! Screenshots!
  • Choosing a license: On what basis? Never lose track of the objectives you set up at the beginning. (In other words: Start with Why ;-)
  • Do you want people to contribute? <- Create contributor guidelines. If not sure, check other projects.
  • Documentation:
    • The code
    • How to use the program <- Examples
    • How to extend it <- Examples?
    • Hosted (and beautiful documentation) on ReadTheDocs
  • More technical: Releases <- Zenodo!
  • Maintenance of the project: Master/Develop/Feature branch. Don't do all in master or people will get frustrated.
    • Pull requests?
  • How to evaluate Development costs of open source software
  • How to evaluate Maintenance costs of open source projects
  • How to create and maintain a community beyond the code
    • Sync/Async communication
    • Respect
    • Foster inclusiveness

Tags: #Open-Source #courses


These are the other notes that link to this one.


Join my experiment of better thinking and interesting discussions
Aquiles Carattino
Aquiles Carattino
This note you are reading is part of my digital garden. Follow the links to learn more, and remember that these notes evolve over time. After all, this website is not a blog.
© 2021 Aquiles Carattino
Privacy Policy
This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License.