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

• All changes should be made using GitHub pull requests. We require two reviewers to approve prior to merge.
• If you have commit/merge access, follow the Rules For Git Committers
• Create branches and use them for code review

Keep commits and pull requests focused on a single purpose

Commits and pull requests should be focused, they should "do one thing" NOT "do this thing, and also this unrelated thing." This applies at both the commit and PR level. Small, focused pull requests are easy to review and approve (or reject!.) The more changes you try to squeeze into one PR, the more likelihood there is of a large uncontroversial change being held up by one small, inessential change.

Hint: if you make unrelated changes to the same file during your development you can use git add -p to interactively select which hunks to include in your local commits, and git cherry-pick to build up a PR branch out of selected commits from a working branch. There are various ways split and regroup your commits, for example git cherry-pick --no-commit <commit> pulls the change without committing, then you can use git reset -p to interactively unstage hunks prior to committing.

Write meaningful commit messages

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

Do not alter existing commits of a PR that has received review feedback

Please preserve the commit history of your code changes during PR review. For example, do not squash commits, or force push an entirely new version of the PR once a review has started. Reviewers need to be able to see the diff between the old code that they requested changes against, and the changes that you made.

You may submit multiple commits in a single PR

A PR may contain multiple commits, but each commit should leave the codebase in a stable production-ready state, and taken as a whole the PR should still "do one thing." If you intend a multi-commit PR to be squashed, or kept separate, please indicate that clearly in the PR description.

DO:

• Use multiple commits to separate a series of code transformations that clarify the purpose of changes and/or simplify code review

DON'T:

• Submit a PR with your full development history including fixups, false starts, etc. (Squash your changes locally prior to submitting the PR.) [But see previous guideline: once the review starts do not alter existing commits.]

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