How To Contribute
=================

So you want to contribute missions for [LRAUVs] to make them do amazing
things for marine science. That's *great* -- here's how to get started:

* [The Short Version](#the-short-version)
* [Getting Set Up To Contribute](#getting-set-up-to-contribute)
* [Composing a New Mission](#composing-a-new-mission)
* [Revising an Existing Mission](#revising-an-existing-mission)
* [Validating Your XML](#validating-your-xml)
* [Submitting Your Changes](#submitting-your-changes)
* [Cleaning up](#cleaning-up)
* [Reporting Bugs](README.md#reporting-bugs)

The Short Version
-----------------
Once you're already set up, these are the main steps you'll need to
remember:

```bash
$ git clone git@bitbucket.org:user/lrauv-mission.git # clone your personal fork
$ pushd lrauv-mission # move into your local clone
$ git checkout -b some-feature # make a feature branch
```

Then [add your new mission](#composing-a-new-mission) or [revise an
existing mission](#revising-an-existing-mission).

```bash
$ git push origin some-branch # push your feature branch to Bitbucket
```

Then log into Bitbucket and file a pull request.

This is exactly what Bitbucket covers in their [example for making a
pull request].

Getting Set Up To Contribute
----------------------------

We use a [Forking Workflow] in the `git` repositories for the [LRAUVs].
This means that each contributor has their own server-side repository.
You will be able to clone that repository, add or edit missions, commit
changes, and push them back to Bitbucket *without affecting the
official repository*. Then, when your mission is complete and tested,
you will file a [pull request] to merge your changes into the `master`
branch of the official repository. [Pull request][pull request]s are a
good way to facilitate discussions on changes before integrating them
into the official repository, and let you add supporting information
like figures from simulation or field tests, and a description of what
the mission is intended to do. It's also a good idea to collect related
changes into a feature branch in your personal repository, and file the
[pull request] to integrate your feature branch into the upstream
remote's `master` branch.

0. Set up your account

   - [Sign up for Bitbucket](https://bitbucket.org/account/signup/)

   - Join the MBARI team by emailing Brian Schlining.

   - Add your RSA keys for [SSH access] (recommended)

     If you are logged in on a terminal instead of a display manager
     (e.g., when working on one of the CentOS virtual machines) and do
     not want to type the passphrase for your RSA key more than once:

     ```bash
     $ eval `ssh-agent`
     $ ssh-add ~/.ssh/id_rsa
     ```

1. [Fork] the mission repository in Bitbucket with the `Fork` button.

2. Clone your personal mission repository to your local machine.

   ```bash
   $ git clone git@bitbucket.org:user/lrauv-mission.git Missions
   $ cd Missions
   ```

3. Make a new branch to work on your mission changes.

   ```bash
   $ git git checkout -b best-mission-ever
   ```

Composing a New Mission
-----------------------

You probably want to copy an existing mission and
[revise it](#revising-an-existing-mission) instead. I recommend
starting with a mission that is used often, like [`sci2.xml`][sci2]:

```bash
$ cp Science/sci2.xml Science/best.xml
```

But otherwise:

- Read [the old OCEANS paper] and the [TethysScript XML Schemas].

- Start with an empty text file, save it with the `.xml` extension.

Proceed with caution, validate and simulate often.

Revising an Existing Mission
----------------------------

Revise, validating and simulating often.

Validating Your XML
-------------------

Please keep in mind the following considerations toward a valid and usable
mission script not only for execution by the LRAUV framework:

* Use an `Id` in the mission file that matches the _simple name_ of the file,
  that is, with no path and no extension. For example, if the file name is
  `Science/smear_yoyo_sampling.xml`, then set `Id="smear_yoyo_sampling"`
  in the `<Mission>` section of the contents.
   
* In principle(*), mission scripts are to comply with the
  [Tethys XML Schemas](http://okeanids.mbari.org/tethys/Xml)
  that are automatically generated from the lrauv-application code
  such that references to various elements as well as overall
  structure of the scripts are correct. This compliance can be
  checked with a typical XML validator (see below).
  
    However, recognizing that even with the assistance of an XML
    validator it is not always as straightforward to apply any required
    fixes, we are currently not requiring full compliance, but we do
    encourage you to do what you can.
    
    Typically, editors or IDEs with support for XML editing should also
    provide a mechanism to perform validation against associated schemas.
    Please consult the documentation of your editor in this regard and
    let the team know about the tools that you use for possible assistance.
    If practical and convenient, please also consider the use of online
    tools for this purpose.
    (We are also considering putting in place some automatic validation
    as part of a push or pull request.)
    
    > (*) Note: The LRAUV framework is actually lenient regarding strict adherence
    > to the schemas (and, in fact, several routinely used mission scripts
    > are not compliant). However, toward increased robustness in the overall
    > execution framework, but also in consideration for other components that
    > make use of the mission information (TethysL, visualization of waypoint
    > trajectories in the Dash, parameter analysis for the status widget, etc.),
    > we envision full compliance in the future.


Submitting Your Changes
-----------------------

Review what you have changed.

```bash
$ git add Science/best.xml
$ git status
$ git diff --staged
```

Use `git checkout -- <file>` to unstage any changes you do not want to
commit.

Commit your changes to your local clone (do this while working to track
your changes). Include a message with a summary of the commit.

```bash
$ git commit -m"Add best mission ever"
```

If you are making big changes, please include an explanation in the
message, following these guidelines:

- The first line is commit summary, 50 characters or less.

- Next is an empty line.

- Then explain the commit in more detail, using as many lines as
  necessary, each with 72 characters or fewer. (Links may be longer.)

- Use [markdown] if you want messages to show up nicely on Bitbucket.

See [a note about git commit messages] for more.

Push your changes to your personal fork.

```bash
$ git push origin best-mission-ever
```

Go to your fork on Bitbucket and file a [pull request].

Cleaning up
-----------

After your [pull request] is submitted, you should get yourself back
onto `master`, so that `git pull` will update your local clone.

```bash
$ git checkout master
```


-------------
This document was originally written drawing from [the contribution
instructions for homebrew casks](https://github.com/caskroom/homebrew-cask/blob/master/CONTRIBUTING.md)

[a note about git commit messages]: http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
[example for making a pull request]: https://www.atlassian.com/git/tutorials/making-a-pull-request/example
[Fork]: https://confluence.atlassian.com/bitbucket/forking-a-repository-221449527.html
[Forking Workflow]: https://www.atlassian.com/git/tutorials/comparing-workflows/forking-workflow/
[LRAUVs]: http://www.mbari.org/auv/LRAUV.htm
[markdown]: https://bitbucket.org/tutorials/markdowndemo
[pull request]: https://www.atlassian.com/git/tutorials/making-a-pull-request/
[sci2]: https://bitbucket.org/mbari/lrauv-mission/src/d449ab2/Science/sci2.xml?at=master
[SSH access]: https://confluence.atlassian.com/bitbucket/use-the-ssh-protocol-with-bitbucket-cloud-221449711.html