Home
Welcome to the Hedy Developer Guide! This wiki will help you to contribute to Hedy. This page explains how we collaborate in the Hedy repository. Please read this before doing anything else!
Hedy is a project in which we communicate with each other in a nice and constructive way. Negative comments on people, code, or anything else are not allowed. Everyone in this repo, whether that are volunteer contributors, students, teachers or people that sometime work on Hedy in a paid capacity, is doing their best. If you find bugs, assume someone tried to do better. If you see code written in a way that you'd never do or recommend, assume it is written by a beginner or someone on a tight deadline. I am sure you too have done such things!
We call the assumption that code is as it is, for a good reason, and asking questions rather than making judgements "the Hedy way". Behaving like that matters to us all personally.
Understand that many of the people working on Hedy are volunteers that spend their brief time on this planet to help with the Hedy misssion. If we want to keep people involved, it is very important to treat them well!
When you comment on issues or pull requests, "do's" are:
- Welcome newcomers to the repo (tip: hovering over a PR author will show you if people are new, see image below)
- Thank people for their efforts
- Give out compliments for things you like
- Inquire why things are as they are rather than demand change
- Offer concrete help in a constructive way
Here is an exemplary PR review from JPelay that shows that we strive for.
This is what a newcomer PR looks like if you hover over the author (from the above PR).
When you comment on issues or pull requests, "don't's" are:
- Demand action from the PR author ("You should...", "I want...")
- Give advice or help when none is asked for, or when none is needed to move the PR forward. If people want input, assume that will ask for it.
Hedy was started as a small prototype by Felienne. It was not necessarily made as a large open source project with many users and contributors and some decisions were made for pragmatic reasons, or sometimes without reasons at all. So you might frown about some decisions here and there, and so do we sometimes! Since the release of the frist prototype at the end of 2019, a lot of people started to contribute without a lot of strategy or process, so code looks very differently in different places of the codebase, and we are still working to get that to a more professional level.
Some people say that there are two types of software: software without users whose source code in a pristine state, and software with users and a lot of issues in code quality. We surely are the latter!
If you are a programmer, you will probably want to start programming, or maybe even cleaning stuff up. We understand! But the best thing to do it so get to know the Hedy product first. Our most successful contributors fall in love with the idea, goals and philosophy of Hedy first, and look around to see where help is needed. Less successful contributors find small issues that bug them and submit pull requests without looking at issues that we created. While that might seem useful, it will overwhelm us and draw attention away from other things. If you are looking for a project to contribute to without getting to know the product, the project, the team, and design philosophy, this is probably not the project for you.
A great first step is to watch an overview of Hedy and its history as presented on Strangeloop in 2022.
Now that you have a sense of what Hedy is, the next step is to decide what you are excited about to work on!
If you are looking for something small, explore these two categories of issues:
- Good first issues are issues that we think are doable for people new to the project.
- Approved are issues we have decided we want to move forward.
Do you want to pick up something bigger? Take a look at the road map!
Before you submit a pull request, understand that anything you submit will cost energy from the contributors. So you might think you are helpful with a tiny change fixing a tiny typo, or with cleanup of the whole code base, but someone will have to read it, evaluate it and merge it. So we ask you to first make changes that are actually needed, approved and good first issue. For any issue in these two categories, we'd be happy to get pull requests, and we are happy to help to get you started on working!
If you want to work on an open issue without these labels, reach out to us on Discord first, to prevent disappointment if we close unwanted pull requests.
We also have bi-weekly contributors meetings on Tuesdays at 7:30 CET (dates and link are in Discord) where we discuss larger issues and plans. Because the Hedy way means communicating with each other in a nice way, we prefer meetings where there is more bandwidth to communicate, including gestures and facial expressions. In between meetings, we sync on Discord. We hope to see you in meetings, and look forward to your contributions!
The core team uses the Project Board to keep track of what we are currently working on, and Discussions to organize things that we are considering. Feel free to browse these to get a sense for what is going on.
In principle, Felienne is the owner of the Hedy project, the repository and thus makes the final decisions. In practice though, decisions are discussed in Github, Discord and in the meetings, and are made respecting the Hedy philosophy of participatory decision making. Often decisions are made by people who are impacted most, either users or programmers extensively working on features.
When you create a pull request (PR), someone will take a look and see whether all is in order. It really helps if you let us know how to test the PR (this is also documented in the PR template) and if you yourself make sure all is in order by running the tests locally.
If the PR is approved, it will be merged with a mergify script. Please don't do anything (esp. don't enable auto merge), all will be handled automatically. Mergify will also tell you that when the PR is approved.
When your PR is accepted into main, that version will be deployed on hedy-alpha.herokuapp.com.
We do periodic deploys of main to the production version of Hedy. You can use the version log to see which version of Hedy lives on the website.