DeveloperGuidelines

Guide to making life easy for everyone

An important aspect of distributed development is having everyone know what everyone else is doing (or not doing). When people only communicate via email, and often only when something goes wrong (a bug report for example), it's hard to keep track of who is doing what, who is planning to do something, who needs help, and so on. The tools PortAudio developers use offer a number of mechanisms to help with this. The main ones are:

• The ticket system for tracking development tasks.
• Doxygen generated documentation
• The portaudio mailing list for discussions between developers and users.
• The PortAudio wiki
• Change proposals - more formalised documents for API changes (most recently used for the V19 API update).

Use Git responsibly

• Follow the Rules For SVN Committers
• Create branches and use them for code review

Write meaningful commit messages

If you write meaningful commit messages other people can see what you're working on.

Add all future tasks to the ticket system

If you think of a task that needs to be done, but you haven't done it yet, or you want someone else to do it, create a new ticket: https://github.com/PortAudio/portaudio/issues/new If you don't have Ticket admin privileges email rossb@audiomulch.com and you'll be given some, it's that simple.

Cross-referencing commits and issue tickets

You can cross-reference an Issue or Pull Requests by putting the number with a # before it. Keep things cross-referenced whenever you can.

You can mark a Pull Request as fixing an issue, for example 123, by writing: Fixes #123

When the Pull Request is merged, the Issue will automatically be closed. So don't use this if there are remaining tasks like documentation or testing to be done.

Post patches to the ticket system

If someone sends you a patch, but you can't/won't action it, at least create a new ticket with the patch attached. https://github.com/PortAudio/portaudio/issues/new

There are a couple of other things that can be done to help us keep track of where each other is up to (what has been done, what hasn't been done, what we're thinking about doing):

Don't use doxygen @todo comments

We used to have a guideline to use doxygen @todo tags in the code. Don't do that. If you find things in the code that need doing, please create a ticket.

Don't forget the style guide

There are PortAudio coding style guidelines, they live here:

Implementation Style Guidelines