First off: thank you. You will be helping build software that distributes clothes and food to thousands of refugees and other people in need. It gives comfort and dignity to people in a vulnerable situation. That can't be said for most open source contributions.
If you haven't done so already, join the #dev channel in our Slack group. That is where all the people who build Boxtribute are. It's a great place to ask questions. If you are new, please introduce yourself in the #introductions channel.
A couple of quick things:
- Once a week we e-meet! We meet online usually once a week on the weekend to distribute tasks. This call usually takes about an hour. Check out the slack #dev channel for more details.
- Do you need help using Boxtribute? Join our Slack group and ask in the #support channel. Psst. We also wrote some doc about how to use Boxtribute
- Have you found a bug, or got an idea for a feature? Write us!
For everything else, please read on...
- Start small. Contributing to a new project can be quite daunting.
- Be bold! If there is something that needs fixing, go for it.
- Make sure your idea has support. Before spending a lot of time on a feature, it's worth checking that it is wanted first. Ask around in Slack and our product owners.
- Write tests, if you can. We are a young project, so we move fast (and break things, unfortunately). But, if you have time, it is worth writing tests for your work. That way we can confirm that the code you are contributing does what you say it does, and we can ensure it doesn't break in the future.
- Constructive criticism If you do not like a contribution, feel free to air it. However, before doing so think first about how to improve and propose alternative solutions.
First, set up a development environment using the instructions in the readme. Once you have made your change, submit a pull request with a clear description of what you have done and why. Reference any issues that are relevant. Please write good commit messages, ideally as a series of logical commits by "squashing" them. (Don't worry if you don't know how to squash commits - we can do that when we merge your code.)
When creating Pull Requests, please add a link to the card/issue/task you worked and link the PR vice-versa at the task. The PR description should include an explanation of why you ended up with the solution you did and the intended behavior. Be clear, especially if you had to make a ‘call’ diverging from the description.
If you haven't contributed to open source before, take a look at this guide. If you haven't used Git or GitHub before, this is a tutorial that will help. Don't be afraid to ask for help, if you need it. (Everyone is a beginner at some point!)
You can contribute in lots of ways that aren't code, too. For example:
- Join our Slack group and help people in the #support channel..
- Get in touch! If you want to give us your opinion or just generally offer your time to help us, feel always welcome to contact us!
These are the principles that have guided our development so far. If you're making a major contribution, it may be worth keeping them in mind.
- Use boring, well-established technology. Boxtribute needs to keep on working for a long time with minimal work. We don't want to have to rewrite it every year because a technology we are using has gone out of fashion.
- Minimal maintenance. We don't have an operations team, nor anyone who can commit to being on-call. The app should run with minimal server-poking.
- Keep it simple. 50 lines of straightforward, readable code is better than 10 lines of magic that nobody can understand. (source)
- Optimize for contributions. The code needs to be approachable and easy to understand, particularly for junior developers. Consider whether that clever new technology is worth it if a junior developer will struggle to get their head around it.
- Move fast and don't break things. We should ship continuously, but use browser tests to avoid breaking things. These tests should check the basic tasks users need to do to get their jobs done.