Orasound's perspective on best practices for open source software design and development. If you are new to open source, we recommend you start with this guide to contributing.
In general, Orcasound developers favor a fork and PR model for building software collaboratively. Although we initially used a feature branch development model for the [orcasite] repo, as our community grew we found that it slowed us down -- especially new or short-term contributors who did were not yet members of our Github organization.
At Orcasound, we follow a user-centered design philosphy. For each project, we try to research our users, or prospective users. We also use the Orcasound open roadmap and other tools to prioritize feature requests based on what users suggest, rather than on e.g. what our devs can make easily.
The skill of collaborating with others is most important in the world of open source. -- Dhananjay Purohit, 2021 Orcasound GSoC student
- Communicate frequently. The team you are working with should know which thing you are working on and how you are approaching a problem.
- Get early feedback on your ideas and approach. It may help you find a much more efficient path to a solution, and it averts PRs that require extensive reviews.
- Work in the open. Don’t keep your changes locally for a week and then push 50 commits to the repo. Early feedback from others will help you be more efficient and it’s easier to discuss issues/changes if your peers can see the code.
- Try to solve problems by yourself, but also ask for help! You should spend a few hours or even a day trying to solve a problem by yourself or with help from on-line resources. However, you shouldn't struggle for more than a few days or a week without asking an Orcasound community member for help.
- Split your changes into separate pull requests. Try to deliver just one incremental change or new feature in each PR. For bigger projects this will benefit you because review and merging of your changes will be faster.
- Write tests early. You can even add them before working on the functional bits.
- Document your code and APIs from the start. Documentation is critical, especially since everything we're building for conserving orcas we hope will prove useful to others working to conserve soniferous species, or to re-purpose Orcasound code for other applications.
Knowledge of Git and Github are also important when collaborating with Orcasound on open source code. Here are related resources that past students and other contributors have found useful:
- Glossary of Git commands
- How to Write a Git Commit Message
- How to keep your Git history clean with interactive rebase
- Set up linting and testing in your continuous integration. Every developer likes green checks on PRs!
- Knowing git(hub) basics is a must, but you might want to learn some new tricks like rebase or bisect.
- Some other helpful tricks: git hooks (and particularly pre-commit tool) and conventional commits.
- The anatomy of a perfect pull request
- How to contribute to open source projects
- If you have a Mac I encourage you to get GitUp which lets you visualize the changes you have made to your code.
- For open source projects invovling audio, become familiar with ffmpeg. It is a really efficient transcoder of media formats, but also has a ton of utilities for handling audio and performing complex filtering.
- An ffmpgeg pipteline tutorial that I found very useful.
Coming soon...