### Public Lab welcomes and encourages community contributions to our open source software!

This page is intended to:

1. List software projects that Public Lab has incubated and provide links to source code.
2. Collect software development guidelines and best practices for Public Lab projects.
3. Help newcomers figure out how and where to start contributing!

## Getting started

Quick tips for getting involved with the Public Lab codebases:

1. **Set up a GitHub account and install git.**

    If you're not familiar with git, a popular version control software, you can try it out at https://try.github.io.

    Speaking of GitHub...right now, all of Public Lab's open source code is located on GitHub, a website which hosts git repositories.  Setting up a GitHub account is the first step to getting involved with Public Lab's code (and lots of other code).

2. **[Join](http://publiclab.org/wiki/mailing-lists) the Public Lab [developers mailing list](https://groups.google.com/forum/#!forum/plots-dev)**

## Contribution Guidelines

Public Lab software is written in many languages, and each project may have its own guidelines for contributors.  These broad guidelines should serve as general principles to guide your approach to a new Public Lab codebase.

### Contributing using git

Check out this article on [GitHub flow](https://guides.github.com/introduction/flow/index.html), a routine that works great on all git projects and makes Public Lab development super smooth.  

### A sample git workflow

Let's say that a developer and PublicLab community member named Susan decides that she wants to add a feature to MapKnitter. Here's what Susan's workflow might look like:

1. Susan [forks](https://help.github.com/articles/fork-a-repo/) the [publiclab/mapknitter](https://github.com/publiclab/mapknitter) repo on GitHub.
2. Susan [clones](http://git-scm.com/book/en/v2/Git-Basics-Getting-a-Git-Repository#Cloning-an-Existing-Repository) the forked repository susan/mapknitter. This downloads a copy of Susan's version of mapknitter to her computer.
3. She creates a branch for the new feature (a *feature branch*).  Let's say that Susan wanted users to be able to tag maps. She might then create and checkout a new branch called `add-map-tags` with: `git checkout -b add-map-tags`. 
4. Susan develops the new feature in the `add-map-tags` feature branch.
5. When Susan is done developing the new feature, she switches back to the master branch of her own repository: `git checkout master`, and then pulls the latest version of mapknitter down from the `publiclab repo` with `git pull publiclab master`.
6. Susan applies her new feature on top of the latest version of mapknitter: `git rebase add-map-tags --onto master`. **This is the great strength of doing development in a feature branch - it allows Susan to merge her changes into the latest public version of mapknitter on her own computer and to resolve any conflicts locally..**
7. After rebasing, Susan's local master branch contains the latest version of mapknitter with her new feature added on top. The new feature is ready, so Susan [submits a pull request on GitHub](https://help.github.com/articles/using-pull-requests/).
8. Susan discusses her code with others. After any questions or change requests have been resolved, Susan's request is merged in, and her contribution becomes part of MapKnitter!

A few notes - some git best practices that will make all of our lives easier:

* Remember to pull from `master` before you start working.  This helps keep your local repository in sync with the code that everyone else is working on.
* Always do development in a feature branch.  This makes it much easier for project maintainers to merge your contributions into the trunk.  The name of your branch is displayed when it is merged in to the main trunk, which means that it serves as built-in documentation for your feature.  This works great when you give your feature branches descriptive names!  Some example branch names:
    * donation-button-redesign
    * markdown-package-update
    * fix#44 (fixes GitHub issue #44 in this repository)
* Open a pull request early! In fact, feel free to open a pull request as soon as you start working on a new feature or bugfix. GitHub's pull request pages make it easy to see progress that's been made on an issue, and it's a great way to start an open and ongoing discussion with the project's maintainers and other contributors about your work.

### Contributing to Ruby projects

### Contributing to JavaScript projects


## Public Lab Software

<table>
<tr>
    <th>Project</th>
    <th>Description</th>
    <th>Source Code</th>
</tr>
<tr>
    <td><a href="https://mapknitter.org/">MapKnitter</a></td>
    <td>Assemble aerial images into maps.</td>
    <td><a href="https://github.com/publiclab/mapknitter">github:publiclab/mapknitter</a></td>
</tr>
<tr>
    <td><a href="https://spectralworkbench.org/">Spectral Workbench</a></td>
    <td>Material analysis using DIY spectrometry.</td>
    <td><a href="https://github.com/publiclab/spectral-workbench">github:spectral-workbench</a></td>
</tr>
<tr>
    <td>Leaflet.Illustrate</td>
    <td>Leaflet plugin built for MapKnitter. Enables text annotations on Leaflet maps.</td>
    <td><a href="https://github.com/manleyjster/Leaflet.Illustrate">github:manleyjster/Leaflet.Illustrate</a></td>
</tr>
<tr>
    <td>Leaflet.DistortableImage</td>
    <td>Leaflet plugin built for MapKnitter. Enables images to be distorted.</td>
    <td><a href="https://github.com/publiclab/Leaflet.DistortableImage">github:publiclab/Leaflet.DistortableImage</a></td>
</tr>
<tr>
    <td>publiclab.org</td>
    <td>This very website!</td>
    <td><a href="https://github.com/publiclab/plots2">github:publiclab/plots2</a></td>
</tr>
<tr>
    <td>Infragram</td>
    <td>Analyze plant health with infrared imagery.</td>
    <td><a href="https://github.com/p-v-o-s/infragram-js">github:p-v-o-s/infragram-js</a></td>
</tr>
<tr>
    <td>MapMill</td>
    <td>Upload and collaboratively rank large batches of aerial imagery.</td>
    <td><a href="https://github.com/publiclab/mapmill">github:publiclab/mapmill</a></td>
</tr>
</table>