First and foremost, thank you! We appreciate that you want to contribute to SuperCollider. Your time is valuable, and your contributions mean a lot to us.
This page is the new home for the document formerly known as
CONTRIBUTING.md. It serves as a quick onboarding guide for SuperCollider developers.
You may also be looking for the SuperCollider documentation.
Joining the Community
SuperCollider users and developers communicate on a number of different channels. Here's how to access them:
- Sign up for a GitHub account and give us a star.
- Join the sc-users and sc-dev mailing lists.
- Join the forums for a more modern alternative to the listservs.
- Join our Slack channel. It's not mandatory, but it's very convenient for talking to other devs!
- Watch the above channels for announcements of our weekly-ish developer calls on Skype. Everyone is welcome to join them!
What does "contributing" mean?
Creating an issue is the simplest form of contributing to a project. But there are many ways to contribute, including the following:
- Updating or correcting documentation
- Fixing an open issue
- Requesting a feature
- Reporting a bug
- Translating the IDE into a language you know (see Additional resources below)
- Creating a Request for Comments (RFC) to propose 'something big'
If you're new to this project, check out the issues tagged "good first issue" – fixing one of these is a great way to get started as a contributor!
If you'd like to learn more about contributing to open source projects in general, the Guide to Idiomatic Contributing has a lot of useful information.
Before creating an issue
The purpose of the issue tracker is not just to report that there's a problem with SuperCollider, but to effectively communicate what the problem is so that others can easily help reach a resolution.
Investigate the issue: What is the minimum effort or code required to produce the issue? Does it happen every time? Can you get it to happen on someone else's computer? Someone else's operating system?
See if a ticket already exists: Search SuperCollider's open issues. If an issue for your problem already exists, it may be appropriate to leave a polite comment stating that you can reproduce it on your system, plus any additional info that isn't already known in the issue thread.
Ask the community: If you feel that you need some help investigating the issue, it may help to ask sc-dev, sc-users, or Slack.
Fill out the issue template: Once you feel that you have information for an effective issue, file an issue on the GitHub issue tracker and fill out the template. Please don't erase the template — it's there to help structure your report effectively.
Be sure to create your issue in the appropriate repository. Note that sc3-plugins are maintained in their own repository separate from SuperCollider.
One ticket at a time: If you have multiple issues to report, please open separate tickets for each one.
Creating an issue
We have provided an issue template for you to fill out so that the basic gist of the issue is easily determined at a glance. Please don't erase the template. It's there for a reason.
When an issue involves a crashing or unresponsive executable and you don't know why, providing a crash report can give developers a very helpful first step toward resolving the problem. See "Generating a crash report" below for instructions for your platform.
Above and beyond
Here are some tips for creating idiomatic issues. Taking just a little bit extra time will make your issue easier to read, easier to resolve, more likely to be found by others who have the same or similar issue in the future.
- Take some time to learn basic markdown. This markdown cheatsheet is super helpful, as is the GitHub guide to basic markdown.
- Learn about GitHub Flavored Markdown. And if you want to really go above and beyond, read mastering markdown.
- Use backticks to wrap code. This ensures that code will retain its format, making it much more readable to others
- Use syntax highlighting by adding "supercollider" or the appropriate language name after the first "code fence" ("```supercollider")
Pull Requests (PRs)
Before working on a pull request, consider whether it might be better to go through the Request for Comments (RFC) process first!
SuperCollider uses the git-flow branching model. We use the
develop branch for new features, deprecations, and breaking changes, and we use the
3.10 branch for bug fixes for the next 3.10.x patch release that have no chance of breaking anything.
If you aren't too familiar with git, please see our guide: Creating pull requests.
Please don't change the title of this section — it is the new location of
DEVELOPING.md, which links here.
Check the sidebar for a full list of reference documents for SuperCollider development. Here are a few that are particularly good for new contributors:
- Project Structure
- Creating pull requests
- Reviewer Instructions
- git cheat sheet
- Code style guidelines
- C++ code style guidelines
- C++ formatting instructions
- Unit Testing Guide
Sorry if the project documentation is a little bit disorderly — it's always a work in progress. If you ever run into confusion or need help, you are always free to ask.