|
| 1 | +# Contributing |
| 2 | + |
| 3 | +Hello! If you are interested in contributing to Sonic Pi in some way, fantastic. Everyone is welcome to help! |
| 4 | + |
| 5 | +Are you wondering about the different ways you might be able to contribute? See [TYPES-OF-CONTRIBUTIONS.md](https://github.com/sonic-pi-net/sonic-pi/TYPES-OF-CONTRIBUTIONS.md). |
| 6 | + |
| 7 | +Do you want to know about all the new features that we'd love to see included in Sonic Pi? See [the Sonic Pi features project board](https://github.com/orgs/sonic-pi-net/projects/1). |
| 8 | + |
| 9 | +## Understanding the Sonic Pi source code |
| 10 | +There are several ways that you can learn more about the technical design of the Sonic Pi source code. |
| 11 | +- You can read brief outlines of the source code structure, and see a diagram of the major components, available from the 'Development' section of the sidebar on the [Sonic Pi wiki](https://github.com/sonic-pi-net/sonic-pi/wiki). _**Note: these are all out-of-date to varying degrees and we are in the process of updating them - so for any serious use, feel free to talk with us directly in the mean-time.**_ |
| 12 | +- You can study the source code itself at our official [Sonic Pi GitHub repository](https://github.com/sonic-pi-net/sonic-pi) |
| 13 | +- You can ask the core development team or wider Sonic Pi community questions at any of the places we gather as a [community](https://github.com/sonic-pi-net/sonic-pi/COMMUNITY.md) |
| 14 | + |
| 15 | +## Project and development process guidelines |
| 16 | +There are several guidelines that we value when planning the format of new work. We encourage community contributors to keep these in mind also when thinking about contributing to Sonic Pi. They are: |
| 17 | + |
| 18 | +- We prefer to limit the number of different technologies/frameworks/languages used in the project where practical |
| 19 | +- We prefer friendly, conversational style for documentation over formal language |
| 20 | +- In line with the core aims of the project, we want Sonic Pi features to be simple enough for a 10 year old child to understand and use |
| 21 | +- We prefer proposed contributions, as well as the technical choices made when building them, to have clear benefits that outweigh any downsides |
| 22 | +- We prefer not to introduce potential instability or uncertainty into the code that is used in the app's build process unless there is a really good reason to do so |
| 23 | +- Since the Sonic Pi project is ultimately owned by @samaaron, all contributions need to be in a form that aligns with Sam's vision for the project, and that he will be able to understand and maintain if the original author moves on from the project |
| 24 | + |
| 25 | +Also, regarding the Sonic Pi development process: |
| 26 | +- We don't set development deadlines |
| 27 | +- We merge code into `main` branch for stable releases only, and all work in progress we merge into `dev` branch |
| 28 | +- We want code intended to be merged into the `main` or `dev` branches to be passing all tests where possible |
| 29 | +- We prefer an issue ticket to be raised as soon as possible when a new bug is discovered (ideally within 48 hours) |
| 30 | +- When someone intends to start work on an issue or new feature, they check the [Issues page](https://github.com/sonic-pi-net/sonic-pi/issues) or [the Sonic Pi features project board](https://github.com/orgs/sonic-pi-net/projects/1) first. If the issue or feature is not already being worked on, the person who intends to start it mentions this publicly somewhere. (They can do this by updating the issue ticket, or mentioning it in any of the places we gather as a [community](https://github.com/sonic-pi-net/sonic-pi/COMMUNITY.md), in order to minimise the possibility of duplicated work. |
| 31 | + |
| 32 | +## Ideal process for contributing with code |
| 33 | +1. Familiarise yourself with the part(s) of the code that you wish to contribute towards if necessary. We're always happy to answer questions about the Sonic Pi code! |
| 34 | +2. For complex or large code changes, it's worth initially discussing the potential solutions with the core team and other Sonic Pi contributors - either by opening an issue and labelling it as a feature request, or again by chatting with us at any of the places we gather as a [community](https://github.com/sonic-pi-net/sonic-pi/COMMUNITY.md). |
| 35 | +3. Fork a copy of the Sonic Pi repository to your personal GitHub account. |
| 36 | +4. Clone your fork to your local machine. |
| 37 | +5. Make changes to your local clone of Sonic Pi. |
| 38 | +6. Commit your changes and push them to your fork on GitHub. |
| 39 | +7. Open a Pull Request to the official Sonic Pi repository. |
| 40 | +8. If changes are requested either by bots attached to the Sonic Pi repository, or the core team, make the desired changes and push again to your fork on GitHub. |
| 41 | +9. Once your code has passed review, it will be merged. |
| 42 | + |
| 43 | +(If you need any further help with any of the above steps for preparing a Pull Request for us on GitHub, it's worth searching the [GitHub documentation](https://docs.github.com/) first, but feel free to ask us for help if you're still stuck after that). |
| 44 | + |
| 45 | +**Note**: if it is decided that a contribution will _not_ be included at the time, this does _not_ mean that the effort is not valued! if such a situation occurs, the core team will endeavour to provide an explanation. |
0 commit comments