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:
- Create a new issue in this repo
- Select the Civic Makers Onboarding Checklist for New Volunteers issue type to get started
- complete the checklist of tasks in the issue. When done, close the issue, and let us know!
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.
- The first thing is to read through all of the Notion onboarding documents (thanks Sean and Qing!) to get a good sense of the lay of the land. This will give you a sense of where the devs fit into everything, and a sense of the broader picture. Take your time with this, and ask any questions as you need. The community is here to help.
- The next thing to do will be to raise an issue on the Civic Makers Onboarding project on GitHub, taking note of the onboarding task for devs. This helps get you familiar with the dev side of the project, and helps you to cruise through the various things that you will need to be aware of. Like complicated system, you will only get to know all the moving parts properly as you get familiar with them, but being aware of where things are and how to find things is a really important step. This step needs to be completed before you can get started with dev work.
- Read the README attached to the project you want to work on. Please ask any questions as needed.
- See if you can book a time to talk to one of the leads (see the onboarding docs for the current leads) about all the things that you have learned so far, ask any questions, and to discuss how to contribute from here. Obviously this one is not as much under your control, but hopefully if the leads can’t find the time then they can point you in the right direction. It’s a good chance to somewhat organically see where you and your skills will fit into the system. It’s also just a good chance to talk to us, learn about each other, and start building the relationships.
- See if you can get it running locally. This is then the start of the technical aspect, so please take note of the guidelines below.
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!
- Take a Trello task: assign it to yourself, add any notes as needed.
- You can keep this simple, but if you want to communicate please do - we welcome this, and it makes other people’s lives easier. You can mention anything about this task that you might want to here. Please read the How We Use Trello reference here: https://www.notion.so/Civic-Makers-ba31d86ca9624c01b9569906c5d692f9?p=a040d9930e8944948b5eff65065941c5
- You can reference this Trello task in your PR (see the next section).
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:
- You should fork the project from the original repo.
- Get it running locally.
- For new work create a new branch with an appropriate name.
- Make changes, and commit.
- Push the changes to your repo.
- Make a PR from your repo to the original.
- Respond to correspondence about the PR (if needed).
- Make changes (if needed).
- And on you go..
A few other pointers:
- Meaningful PR messages. These should be roughly aligned with the significance of the PR. For anything complex, be prepared to thoroughly explain in the PR what the aim of the PR is, and how you achieve that aim. Again, this is within reason, but for particularly thorny parts of the code, please explain anything that might need it.
- Add any tags to the PR that are needed (WIP, Spike, etc)
- If the PR is from a Trello task, please add a link to that task.
- If you make some git errors, don’t hesitate to have a chat with someone from the team.
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:
- https://martinfowler.com/articles/on-pair-programming.html
- Agile Alliance - pairing
- https://www.codementor.io/pair-programming
- https://searchsoftwarequality.techtarget.com/definition/mob-programming
- https://www.pluralsight.com/blog/software-development/mob-programming-101
- Agile Alliance - mob programming
- Even if junior, you can read PRs. This is also work. Even if it’s just to say good job, or that you don’t understand something and could it be made clearer. Reading and responding to PRs is a skill, and one that I’m still learning. Dive in, or if you are worried about taking steps, ask someone to give you a hand.
- We love love love people who contribute to the README. If you document your struggles as you go through, these can be excellent elements to add to the README or form the basis for a FAQ. This helps others in a big way.
- Get involved on Slack where you can.
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!