### AvCaster Contribution Guidelines

AvCaster source code, binary assets, and documentation are distributed as [free software](https://www.gnu.org/philosophy/free-sw.html) and [free culture](http://freedomdefined.org/Definition).  To this end, it is necessary for all contributors to be in agreement about this.  This agreement is not a copyright assignment.  It's function is merely to ensure that AvCaster remains free (as in freedom).

In short, this means that as a contributor, you allow others to copy, distribute, and modify their copies or your work; provided that they extend this priviledge to others and credit you as the original author.  This implies that all source materials are made available in their respective preferred forms for modification; so for multimedia, this is all individual source files and/or editor project files in addition to the "mixed-down" binary artifacts.  Refer to the 'Multimedia' section below for details.


### Contribution Licensing Terms

As a contributor, you agree that all contributions to the source tree, wiki, and issue tracker that are unlicensed and not in the public domain will automatically fall under the same appropriate licence as AvCaster: [GPLv3](COPYING.md) for source code, [GNU-FDLv1.3](Documentation/README.md) for documentation, and [GPLv3](Assets/README.md) for multimedia and other binaries (such as audio, video, and images - see below).

If you are not the sole author of your contribution (i.e. it is a combined or derivative work incorporating or based on someone else's work), then all source works must be freely distributable under the terms of some [GPL-compatible license](https://www.gnu.org/licenses/license-list.html#GPLCompatibleLicenses) such as the Creative Commonns CC-BY or in the public domain; and you must clearly give attribution to the copyright holders with hyperlinks to the original sources and licenses.

This is the common "inbound<->outbound" tacet norm and is even made explicit by some public services such as [item 'D6' of the Github Terms of Service](https://help.github.com/articles/github-terms-of-service/#6-contributions-under-repository-license).

#### Multimedia and other Binary Contributions

For multimedia and other binaries, the "sources" or "preferred forms" for modification as required by the GPLv3 are explicitly defined here, in the context of the AvCaster project, to be any and all binary data, meta-data, mappings, composition files, declarative recipes, scripts, and source code of executable media routines that are necessary to accomplish all of the following using only widely-available free software:
* regenerate the associated target artifacts completely and accurately
* modify these "preferred form" decomposed sources directly and individually
* compose the original and modified sources
* generate equivalent modified versions of the associated target artifacts

For example:
* "target artifacts" such as final composite (mixed-down) .png, .wav, .webm, etc (these are typically the only works that are distributed under Crerative Commons and other "Free Culture" licencses)
* "binary data" such as the individual elements that compose the "target artifacts" (uncompressed image layers, isolated sound tracks, etc.)
* "meta-data", "mappings", and "composition files" such as EDL/cue-sheets, .xcf, .psd, .aup, .ardour, etc.
* "declarative recipes", "scripts", and "executable media routines" such as 3D models, animations, SVG images, MIDI data, openGL shaders, etc.
* "widely-available free software" such as GIMP, Inkscape, Audacity, Ardour, Blender, etc. ([free, as in freedom](https://www.gnu.org/philosophy/free-sw.html))

Contributions that do not meet the above criteria will not be accepted and will probably be deleted.


### Developers

You will find in the Builds/Scripts directory some helper scripts to aid in building and debugging this application with gcc and gdb.

Simply run ```Builds/Scripts/setup-build-helpers``` to install them to the av-caster root directory. See Builds/Scripts/README.md for usage.

Generally speaking, the files under the Builds/ directory are not to be modified manually nor should any reconfiguration be done from within an IDE.  This is sometimes useful for experimentation but note that changes made with external tools will not persist.  Inevitably, all project configuration must be done using the Projucer project manager because important files in the Builds/ directories are clobbered by the Projucer upon each save; and the only files under the platform-specific Builds/ directories that should be committed to version control are those generated by Projucer and otherwise unmodified.

Projucer is not relevant to most development tasks, but if you must use it for design or project maintenance, please compile it from the 'gnu-jucer' branch as described in the 'Designers' section below.


### Designers

* Fork the AvCaster repo then clone AvCaster and JUCE locally

```bash
### Clone the design branch locally ###
cd YOUR_DEV_DIR
git clone -b design https://github.com/YOUR_GITHUB_NICK/av-caster

### Clone the Projucer gnu-jucer branch locally ###
cd YOUR_DEV_DIR
git clone -b gnu-jucer --depth 1 https://github.com/bill-auger/JUCE.git juce
```

* Compile via the Makefile or one of the IDE project files under the Builds/ directory
  * juce/extras/Projucer/Builds/LinuxMakefile/
  * juce/extras/Projucer/Builds/MacOSX/
  * juce/extras/Projucer/Builds/VisualStudio2013/
  * juce/extras/Projucer/Builds/VisualStudio2015/
* Copy the Projucer binary from your chosen Builds/ directory to a convenient location
* Run the Projucer
* Browse into the av-caster/ directory where you cloned AvCaster
* Choose the AvCaster.jucer file

Note that the Projucer is not a pixel-perfect WYSIWYG editor.  The premium and trial versions of Project include a live preview on some platforms otherwise you may need to compile AvCaster to see the true representation.  Refer to the "Building from Source" section of the README.md to compile AvCaster.


### Pull Requests

* Developers: please issue pull requests against the [upstream 'development' branch: https://github.com/bill-auger/av-caster](https://github.com/bill-auger/av-caster/tree/development).
* Designers: please issue pull requests against the [upstream 'design' branch: https://github.com/bill-auger/av-caster](https://github.com/bill-auger/av-caster/tree/design).

Note that branches other than 'master' tend to be rebased often so you may need to force pull those.  Please rebase all pull requests onto the latest development or design HEAD and squash trivial commits but try to retain significant notable commits (see example below).  Ideally in this way, all upstream branches should be a fast-foreward from master and so re-sync should be simple.


### Commit Messages

Please add commit messages of the following form:
```
short general description of feature in declarative tense (optional issue #)
<EMPTY LINE>
  * specific notable change
  * specific notable change
  * specific notable change
  * specific notable change

e.g.

add bar powers to the mighty foo (issue #42)

  * added Bar class
  * added height, width instance vars to Bar class
  * added Bar instance var to Foo class
  * added setBar(), getBar() accessors to Foo class
```


### Issue Tracker

Please do not hesitate to use the issue tracker for bug reports, feature requests, constructive notes on existing issues, and significant progress updates that are not yet in a pull request; but use the gitter chat or other channels for lengthy discussions and other issues such as help.
