diff --git a/doc/developer.md b/doc/Developer Guide.md similarity index 80% rename from doc/developer.md rename to doc/Developer Guide.md index 0a3a65cc198..2fbcc102721 100644 --- a/doc/developer.md +++ b/doc/Developer Guide.md @@ -1,12 +1,14 @@ -# Some tips for developing on Surge +# Developer Guide -As we've done several pull requests and reviews, a group of developers have convened on this set of -sort of standards for developing with surge. None of these are set in stone but PR reviewers will -have an easier time if you skew close to them. +## Introduction -And hop on slack anytime if you have questions. Asking before you start is welcome. +This document contains the guidelines that we use in Surge development. Please +follow them whenever possible. If you have further questions look at README.md +for an up to date list of Surge communication channels. -## Code Review Culture +## Contributing + +### Code reviews Code reviews are important parts of pull requests. Folks do them carefully and seriously. But we always are polite and professional. If you think a comment about @@ -17,7 +19,22 @@ But please do expect your code to be reviewed before it is merged, and you may b to make changes. Skewing to these rules nad checking them before you do a PR can help make everyones time more efficient. -## git +### Commit messages + +Format: + +``` + + + +``` + +A tag can be either `Related: ` or `Closes: `. + + +### Github usage * The [git-howto](git-howto.md) is a good basic if you are newer to git. * Generally, try and have a github issue which documents what you are trying to do @@ -30,9 +47,10 @@ could be squashed with `git rebase`. If you don't know how to do this, ask on sl put in the PR with your commits and we can squash at merge * Try to avoid trivial or unrelated diffs. Your diffs should be "about" the same size as your change. -* See the section below on Commit Messages. -## Code Basics +## Coding style + +### Basics * Obey the 'campground rule' that code you change should get better. Cleaner, better names, better indents, more comments. @@ -43,7 +61,7 @@ if that variable name is in 30 other places. * The code is mostly formatted with 3 space tab width, which is odd. If you are in a 3-space section stick to 3 spaces. If you are writing new code we are OK with 3 or 4. But code should align -## Naming +### Naming * `#defined` constants are `UPPERCASE_VARIABLES` * `class HaveCamelcaseNames` @@ -55,7 +73,7 @@ section stick to 3 spaces. If you are writing new code we are OK with 3 or 4. Bu * Use namespaces not classes to group functions. Check out how we implemented `UserInteractions.h` * Long and descriptive names are good. `userMessageDeliveryPipe` is better than `umdp`. -## Comments +### Comments Comments for declarations of member functions or free functions aspires to javadoc/doxygen style. @@ -91,28 +109,7 @@ Use single line comments sparingly, but where appropriate, feel free. Generally: Comment your code. Someone coming after you will thank you. And that someone may be you! -## Commit messages - -Format: - -``` - - - -``` - -A tag can be either `Related: ` or `Closed: `. - -A good example is the commit message from -[8a769c](https://github.com/surge-synthesizer/surge/commit/8a769c87220959997633a32baabe76a2887d6d18) -which @baconpaul rewrote after a review from @jsakkine. - -If you want to change your commit message before doing a PR, you can do `git commit --amend` as documented -[here](https://www.atlassian.com/git/tutorials/rewriting-history) and elsewhere. - -## Miscellany +### Miscellany Occasionally code needs an `#if MAC` but if you have entire classes with parallel implementations just put the implementations in the `src/mac` `src/windows` and `src/linux` directories and @@ -126,4 +123,3 @@ Prefer `std::ostringstream` and so on to `sprintf` and so on. `#pragma once`, while not [really standard](https://en.wikipedia.org/wiki/Pragma_once), is used in most of the code, so we are continuing to use it rather than ifdef guards. -