CONTRIBUTING

## Download

First clone the upstream repository from GitHub:

```
git clone https://github.com/BIMSBbioinfo/pigx_rnaseq.git
```

## Configure

PiGx uses the GNU build system.  Developers need to bootstrap the
build system first with the `bootstrap.sh` script.  Bootstrapping
requires GNU Autoconf and GNU Automake.

```
./bootstrap.sh
```

Bootstrapping creates the `configure` script, a portable shell script.
You need to run the script to configure the package before building.

**IMPORTANT**: The default prefix (path to where tools are installed
to) for installation will be `/usr/local/`, so if you do not have
permissions to write to this location (i.e. do not have root
permission) then just use a different location like a subdirectory
under `$HOME`.

    ./configure --prefix=$HOME/pigx

NOTE: The configure has multiple options, you can see a description using:

```
./configure --help
```

For example, the following command overrides the locations of the
executables for `R`, `Rscript`, and `samtools`, disables checks for
required R packages, and configures the package to be installed in the
current directory:

```
./configure --disable-r-packages-check  \
            R=$HOME/programs/R-3.4.1/bin/R \
            RSCRIPT=$HOME/programs/R-3.4.1/bin/Rscript \
            SAMTOOLS=$HOME/.guix-profile/bin/samtools \
            --prefix=$PWD
```

Be aware that `--disable-r-packages-check` should only be used when
you are certain that all R packages are available at runtime.  It
should not be used when installing the pipeline to a shared location
for all users.


## Building

Even if you don't choose to install the pipeline, you will still need
to build a couple of files.  Do that by running `make`.

If you want to skip the installation step, you will need to set the
environment variable `PIGX_UNINSTALLED` to any value before running
the executable from the current working directory.

Now finally you can call the executable:

```
./pigx-rnaseq tests/sample_sheet.csv -s tests/settings.yaml
```

and you should see the flying pig. :)


## Install

In order to properly set up the packages structure under the prefix
location run:

```
make install
```


## Releases

Releases are made by the core developers only.  This section describes
the release process.

- Any new release tarball should have a unique version number.  This
  is achieved by updating the version string in the `VERSION` file.

- Run the tests and build a new tarball.  Since we are using
  Autotools, we can run the test suite and generate a new release
  tarball with  `make distcheck`.

> NOTE: You will find the output of the check in the installation
> directory ($PREFIX ) under `pigx_rnaseq-0.0.1/_build/test-suite.log`.

- Once the tests pass and you are sure to make the release, create a
  new signed tag with `git tag --sign v$(cat VERSION)`.

- Sign the release tarball with GPG to create a detached signature.

- Push the tag to Github, and then upload the tarball and the detached
  signature to https://github.com/BIMSBbioinfo/pigx_rnaseq/releases