From 3118ae6ba636610f29cbf77789eef628f8afeab4 Mon Sep 17 00:00:00 2001 From: Ethan Crawford Date: Thu, 7 Oct 2021 12:53:38 +0800 Subject: [PATCH] Docs - update contributing docs [ci skip] --- CONTRIBUTING.md | 45 ++++++++++++++++ HOW-TO-CONTRIBUTE.md | 111 -------------------------------------- README.md | 2 +- TYPES-OF-CONTRIBUTIONS.md | 40 ++++++++++++++ 4 files changed, 86 insertions(+), 112 deletions(-) create mode 100644 CONTRIBUTING.md delete mode 100644 HOW-TO-CONTRIBUTE.md create mode 100644 TYPES-OF-CONTRIBUTIONS.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000000..a4252226d6 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,45 @@ +# Contributing + +Hello! If you are interested in contributing to Sonic Pi in some way, fantastic. Everyone is welcome to help! + +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). + +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). + +## Understanding the Sonic Pi source code +There are several ways that you can learn more about the technical design of the Sonic Pi source code. +- 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.**_ +- You can study the source code itself at our official [Sonic Pi GitHub repository](https://github.com/sonic-pi-net/sonic-pi) +- 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) + +## Project and development process guidelines +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: + +- We prefer to limit the number of different technologies/frameworks/languages used in the project where practical +- We prefer friendly, conversational style for documentation over formal language +- 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 +- We prefer proposed contributions, as well as the technical choices made when building them, to have clear benefits that outweigh any downsides +- 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 +- 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 + +Also, regarding the Sonic Pi development process: +- We don't set development deadlines +- We merge code into `main` branch for stable releases only, and all work in progress we merge into `dev` branch +- We want code intended to be merged into the `main` or `dev` branches to be passing all tests where possible +- We prefer an issue ticket to be raised as soon as possible when a new bug is discovered (ideally within 48 hours) +- 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. + +## Ideal process for contributing with code +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! +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). +3. Fork a copy of the Sonic Pi repository to your personal GitHub account. +4. Clone your fork to your local machine. +5. Make changes to your local clone of Sonic Pi. +6. Commit your changes and push them to your fork on GitHub. +7. Open a Pull Request to the official Sonic Pi repository. +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. +9. Once your code has passed review, it will be merged. + +(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). + +**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. diff --git a/HOW-TO-CONTRIBUTE.md b/HOW-TO-CONTRIBUTE.md deleted file mode 100644 index 587b199a60..0000000000 --- a/HOW-TO-CONTRIBUTE.md +++ /dev/null @@ -1,111 +0,0 @@ -# Contributing - -Hey, you like Sonic Pi and want to contribute in some way? -That's great, this is an open source project and you're invited to join! - -## You have an idea? - -If you have any idea on how to improve Sonic Pi, don't hesitate to -[open a new issue](https://github.com/samaaron/sonic-pi/issues) on -GitHub and describe what you have in mind. - -You can also visit the -[Sonic Pi community](https://in-thread.sonic-pi.net/) if you want -to discuss your idea directly. - -## You need an idea? - -If you don't have an itch of your own to scratch, but are still looking -for something to work on, you can first go and browse the -[open issues](https://github.com/samaaron/sonic-pi/issues) on GitHub. -There's probably one among them you can help to fix. - -Next to those, here's a list of ideas, frequent feature requests or -unfinished projects that we didn't have time to work on just yet and -where help is appreciated. - -### Easy Projects - -- Share your teaching material - - You're an educator and you have made your own teaching material? - Then share it with the world! A good place to do so is the - [Sonic Pi community](https://in-thread.sonic-pi.net/). - -- Correct us - - Proofreading is always helpful. If you find a typo or bad writing, - let us know and [open a new issue](https://github.com/samaaron/sonic-pi/issues) - or, even better, send a pull request on GitHub. - -- [Translate Sonic Pi to your language](https://github.com/samaaron/sonic-pi/blob/main/TRANSLATION.md) - - It's a wonderful way to introduce school kids in your country to - Sonic Pi and educators will appreciate it when we make it easier for - their class. The tutorial is fairly long, but the graphical user - interface is quickly translated and a good place to start. - -### Medium Projects - -- Get us in touch with blind or visually impaired users - - We think that Sonic Pi would be a pretty awesome tool for blind or - visually impaired users wanting to learn programming. If you can - help us get in touch with one of these users or are one of them, - please let us know. We don't know if the Sonic Pi GUI is useful - and accessible enough for you, so we don't know where to improve it - for your needs. Your input is highly appreciated. - -- Optimisation: Identify & fix bottlenecks that waste CPU or RAM - - Several different parts work together in Sonic Pi, there's - Supercollider, controlled by a server written in Ruby and - a QT-based GUI on top of it. All this runs on a Raspberry Pi, so even - a small optimisation under the hood may be very helpful in - keeping things smooth. If you love profiling and optimising existing - code we'd love to hear from you. - -- Clean-Up: Fix our build scripts - - The components of Sonic Pi are written in Ruby, C++ and soon Erlang, - pulling in several libraries from various other projects. - - This makes it difficult to maintain a cross-platform build ruleset - and we'd love to have - [easier build scripts](https://twitter.com/despair/status/679136039303278593) - that work on Linux, Windows and OS X. - -### Hard Projects - -- Feature: Add SoundFont support to SuperCollider - - You didn't see it, but you heard it loud and clear: Sonic Pi owes - its awesome sound engine to the brilliant - [SuperCollider](http://supercollider.github.io/) project. - Some of the features we want to see in Sonic Pi actually - require enhancing SuperCollider. One that would be really nice - is native [SoundFont](https://en.wikipedia.org/wiki/SoundFont) support, - which would require writing a - [UGen plugin](https://github.com/supercollider/sc3-plugins) - for SuperCollider. - -- Sync multiple instances of Sonic Pi on the net - - How to play Sonic Pi as an orchestra? Should there be a central - audio server that turns all the clients' code to music? Or is it - possible to synchronise each machine's audio on the net? - -- Mobile devices? Porting to Android? - - These days, school kids have a smartphone or tablet before they have - their own computer. - - It's not possible to build Sonic Pi for iOS, since Apple does not - allow integrating a programming language into iOS apps. - - Technically it should be possible for Android, however nobody has - tried that yet. Are you an Android fanboy and willing to maintain a - port? - - Or maybe we should explore a client/server architecture instead, so - that we gain a path for an iOS app? diff --git a/README.md b/README.md index 00cf97d14f..ebad4c4c67 100644 --- a/README.md +++ b/README.md @@ -88,7 +88,7 @@ Would you like to contribute a translation too? If so, please take a look at our Sonic Pi is under active development, and welcomes new contributors: -* [How to contribute](HOW-TO-CONTRIBUTE.md) +* [Contributing](CONTRIBUTING.md) * [Change log](CHANGELOG.md) * [Community](COMMUNITY.md) * [Contributors](CONTRIBUTORS.md) diff --git a/TYPES-OF-CONTRIBUTIONS.md b/TYPES-OF-CONTRIBUTIONS.md new file mode 100644 index 0000000000..011b80fcd5 --- /dev/null +++ b/TYPES-OF-CONTRIBUTIONS.md @@ -0,0 +1,40 @@ +# Types of contributions + +Hello! Are you interested in contributing to Sonic Pi, but not sure where to start? there are many ways to do so, even besides writing code. +Here's a few ways you can help: + +## Share your Sonic Pi experiences +- Sharing your Sonic Pi experiences with people is a great way to raise awareness of Sonic Pi. Giving talks, performances, tutorials or workshops, sharing resources and teaching materials, or even just posting a simple message on social media about it (on Twitter we're `@Sonic_Pi`) are all ways you can spread the word. For all the different ways people can connect as a community around Sonic Pi, see [COMMUNITY.md](https://github.com/sonic-pi-net/sonic-pi/blob/main/COMMUNITY.md) + +## Help with issues and pull requests on GitHub +- Proof-reading pull requests. If a pull request contains plain text besides code, then spelling and grammar checks are always helpful. The default language is British English (en-GB). +- Adding helpful comments to issues. [The list of issues on GitHub](https://github.com/sonic-pi-net/sonic-pi/issues) can often be quite large - this can become difficult for the core development team to manage, so comments that help to manage this are always welcome. + This could include things like replying to folks: + - Reminders that (politely) point to our [troubleshooting guide](https://github.com/sonic-pi-net/sonic-pi/wiki/Troubleshooting-Issues) + - Help with filling out the issue templates + - Pointers to existing issues that might already describe the same specific problem or request + + Or providing your own extra information to issues: + - More detail to describe the problem + - Potential workarounds or ideas for solutions + +## Raise a feature request +If you have an idea for a new feature or enhancement, search 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 (someone might have raised it already!). +If it's new after all, go ahead and [raise a feature request](https://github.com/sonic-pi-net/sonic-pi/issues/new/choose)! + +You can also visit [the Sonic Pi community forum](https://in-thread.sonic-pi.net/) if you want to discuss your idea more informally. + +## Translate Sonic Pi to your language +It's a wonderful way to introduce school kids in your country to +Sonic Pi and educators will appreciate it when we make it easier for +their class. The tutorial is fairly long, but the graphical user +interface is quickly translated and a good place to start. +For details, see [TRANSLATION.md](https://github.com/sonic-pi-net/sonic-pi/blob/main/TRANSLATION.md) + +## Send us some changes for Sonic Pi in a Pull Request +We're always interested in receiving fixes, new features and improvements for Sonic Pi - even more so in areas that the core team has been unable to focus on! + +If you don't have a specific bug-fix, new feature, or enhancement already in mind, you can always browse the +[open issues](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) on GitHub. +There's probably an issue you can help to fix, or feature request you can help build. +For guidelines to keep in mind while you're preparing your contribution, see [CONTRIBUTING.md](https://github.com/sonic-pi-net/sonic-pi/blob/main/CONTRIBUTING.md)