If you've come here to get started with contributing to the current Civic Makers project, then you're in the right place!
To get started with the onboarding tasks:
See this example onboarding task for more details of what to expect.
Read on for the full intro...
Firstly, welcome aboard and thanks for helping out!
This document will seem serious at times, but the aim is to give you enough information to set expectations about how to best interact on an open-source project with Civic Makers. At the end of the day the reality is that the people involved are super friendly and helpful. This is an attempt to outline some elements to keep in mind given the fragmented nature of working with volunteers of various levels contributing asynchronously. The tech problems are just one of the problems we are solving here.
These are a few thoughts about how to best contribute as a dev.
The first thing is that there might be a lot to get your head around early on, and lots of things that are roadblocks to getting work done early. This can be discouraging, and we are keen to help. Part of that help is in this document, but other parts are going to be encountered by you in ways we haven’t prepared for and you’ll need to know where to go for help. With these types of projects it can be a bit slow and steady, but if you ease through the steps, you’ll get there. You might be keen to contribute straight away, but getting these things done will help to make you more effective.
We also have designers and product owners in the team, and it’s very worthwhile getting to know all the people who will be helping you get your work done. Some of these documents help outline that scope.
Please peruse this whole document before carrying out any steps. Will be good to have this information scanned through once before getting into the work.
Now to the more technical aspects. These are not steps so much as things to keep in mind as you contribute. They are my ideas, and not set in stone. More like guidelines - though if you disagree with anything here, we are happy to discuss it. These aspects are something that everyone should be able to contribute to and have a say in. Many of the points here are a matter of balance, and more something to think about as you progress.
Take your time and describe as much of the context as you can manage. You certainly don’t have to assume zero knowledge, but it is really important to think about how you can make it as clear as possible to someone who might not have all the context but may still be able to help. Taking some time to think about how best to ask the question will help you to get the best sort of responses. It’s much more important than you might think, and small efforts to be thoughtful here have big flow-on effects.
Keep it simple. It can sound really boring saying this, but we just want nice simple code that works and that people can understand. Obviously this is within reason, and is also somewhat subjective. But the first thing to consider when writing the code is how easily it will be understood, and how will it make things easier to be build upon. Remember that this code will need to be read by other developers of different skill levels, so just writing code that works is really the baseline.
An example would be that people are likely to be more irritated than impressed if you try to crush everything into one line. For example:
Depending on the project, the codebase you are stepping into could be very large. If you are experienced, this could be no worries, although a new framework or language may be tricky. By all means get the code running and look through it as you wish, but the truth is that many frameworks bring with them many folders and files that you won't need to understand to get work done. Sometimes it can be very helpful to have someone who knows the project strip away some of the complexity by giving you an introduction into the code base, and essentially pointing you in the direction of the folder or files that you should be concentrating your efforts. Our aim is to help you contribute as best you can, not force you to read through huge codebases as prerequisite - although you are more than welcome to do so should you be interested to do so!
If the project is now up and running for you locally, you might want to make a small and very simple PR to get things rolling, and for practice as much as anything. Could even be some small changes to the README. This can be a good way to get going.
The system:
A few other pointers:
This can be a hugely rewarding exercise, and we would like to see more of it in the group. Perhaps you are interested in how one of the more experienced devs might tackle a task, so feel free to ask if you can be along while they make an attempt. This won’t always be feasible, but sometimes will work.
In other instances you might feel quite junior, and can ask another one or two juniors to help out on a task.
We should also consider mob programming sometimes. This can be very good for spikes and some of the work starting out and getting a few opinions.
Resources:
Things will ebb and flow in how quickly PRs get reviewed, and in many ways. If a PR has been sitting there without a response for a couple of days, you are welcome to politely prod a dev to see if you can get some feedback. At times things might be slow because people are busy with other things. But sometimes your PR (or query or whatever) will just have been lost in the fray. People will usually be happy for polite prodding.
Part of the problem that we are solving in this document is tempering expectations. This project attracts the full spectrum of devs, from the very junior to the very senior, and often the true difficulty of these projects is the management of people rather than the difficulty of solving the coding problems. I’m repeating myself, but this is another factor to consider when contributing.
A few more thoughts. This might all be simple to you, and you might wonder about all the rules. Or this might be a lot to take in and you might find it overwhelming.
On the first point, that's understandable. What you have to consider here is that we are trying to get things done, but also trying to be inclusive. And that all of this is happening with volunteers who also have busy lives, and may have to come and go from the project over time. We are trying to find the balance between being collaborative and inclusive, and getting the job done.
If it’s overwhelming, know that this gets easier. As you use Trello and start making PRs and so on, the confusion will start to drop away. Many of the elements in this document make little sense on the page, and slowly get illuminated over time. You will make mistakes with code, with the system, and in all manner of ways, and that’s all totally fine. Everyone involved is keen to help.
Despite the somewhat serious nature and tone of this document, everyone is very friendly and welcoming, and we are all wanting to help even if other things get in the way from time to time.
Welcome aboard!