FixMyBerlin is an open source project and we would love to receive contributions. If you want to contribute – welcome! Great that you are here!
The project is mostly being developed by FixMyCity GmbH in Berlin. We are working on the platform continuously and see each other face-to-face every week in the co-working area of the city of Berlin, which contributes a lot to our collaboration during development. Nonetheless we want to make it easy to contribute to this project from outside the organisation as well. This document tries to answer some common questions that you might have if you would like to do so. If you have any questions or comments, feel free to open an issue at Github or send a short email to [email protected].
- What should I know before I get started?
- How can I get start developing?
- How Can I start contributing?
- Contacts
- Additional notes
The code running fixmyberlin.de is contained in two repositories, published by the FixMyBerlin GitHub organisation:
| Repository | Purpose |
|---|---|
| /fixmy.platform | Backend for all services and projects we provide. A Django-based Python app. |
| /fixmy.frontend | Web frontend that runs fixmyberlin.de. A React-based Javascript app. |
Your contribution might affect both repositories.
We use issues to track both bugs and tasks. Some of the issue's title and description might seem cryptic because the people working on it are already deep into the matter, however if you are curious - feel free to add your question as a comment or just ask for a general explanation and we will probably be happy to explain in more detail.
We are using GitHub's default labels so look out for issues labeled good first issue or help wanted as these are good starting points for jumping into the code.
The README.md explains how to run the app locally by spawing a development server and how to run our test suite. If you run into any issues doing so, do not hesitate to open an issue with a description of your problem, we might be able to help.
Spotted a bug? Please raise an issue using the provided issue template. Make sure to explain the problem with enough details to help maintainers to reproduce the problem.
- Use a clear and descriptive title for the issue to identify the problem.
- Describe the exact steps that reproduce the problem in as many details as possible.
- Start by explaining how you ran the app. Did you visit https://fixmyberlin.de/? Did you run a local dev server?
- State the the URL where you encountered the bug, e.g. /planungen?
- What did you to to provoke the error? Provide specific examples to demonstrate the steps. Include links to files or GitHub projects, or copy/pasteable snippets, which you use in those examples. If you're providing snippets in the issue, use Markdown code blocks.
- Describe the behavior you observed after following the steps and point out what exactly is the problem with that behavior.
- Explain which behavior you expected to see instead and why.
- Include screenshots and animated GIFs which show you following the described steps and demonstrate the problem. You can use this tool to record GIFs on macOS and Windows, and this tool or this tool on Linux.
If the issue description is not clear enough, ask questions by commenting below it. You can spot suitable issues by their labels.
You have an idea for an improvement to the app? Great!
Please contact us to discuss your idea. Try and make it easy for us to understand your idea. Does your idea add value for a specific kind of user of our app? How do you imagine it to work and look like? Maybe also: How could it be implemented? You don't need to have a solution ready, though.
We love PRs! Before you get to work developing an enormous feature, please get in touch and talk to us, though.
Here is a quick guide for how you make a pull request:
- Fork the repo
- Write new code
- Make sure all tests pass
- Commit your changes. When writing the message, follow the Conventional Commits spec.
- Push to your fork and submit a pull request.
- Within the PR, describe the requested change using the provided pull request template.
FixMyBerlin is developed by a team of developers who regularly talk to each other and plan development in German language. Translating all of our plans into English would create a lot of friction and many chances for miscommunication.
Since tasks are often also discussed in person in our office, in video calls or defined in external documents, we don't always add full documentation to the descriptions of our tickets. Instead we often use tickets to record the progress of tasks well-known.
However, we are trying to explicitly create points of entry for anyone interested in joining in on the development of the project. Please refer to the section about labeling) to find well-documented examples of good first issues.