mainpage.dox

/*! \mainpage Developer's Documentation

@section intro_sec Introduction

This documentation is focused on the developer of [pgRouting](http://pgrouting.org).

A developer might want to:

  - Fix a bug
  - Add new functionality
  - Modify the documentation
  - Add tests
    - regression
    - benchmark

The following steps are based on:
  - [My Experience with GitHub](https://github.com/pgRouting/pgrouting/wiki/My-Experience-with-GitHub)
wirtten by Mohamed Zia
  - [Git Branch Model](http://nvie.com/posts/a-successful-git-branching-model)

@section install_sec Installation for developing


Step by Step processing

1. Create a fork of the original [pgRouting](https://github.com/pgRouting/pgrouting) repository.
   - If you don't have an account in Github, please [create one](https://github.com/)
     - for purposes of this document the account name is: `acountName`
   - Navigate to [pgRouting](https://github.com/pgRouting/pgrouting) repository.
   - In the top-right corner of the page, click Fork.
   - Additional information can be found in [fork-a-repo](https://help.github.com/articles/fork-a-repo)

2. Now create a local clone of your above created fork
   - [set up Git](https://help.github.com/articles/set-up-git) in your computer.
   - clone your repo
~~~~{.c}
     git clone https://github.com/acountName/pgrouting pgrouting
~~~~

3. Go to your repo
~~~~{.c}
     cd pgrouting
~~~~

4. Setting the remote fetching connections
   - [More on remotes](https://help.github.com/categories/managing-remotes/) .
   - check the remote connection
~~~~{.c}
    git remote -v
~~~~
   -  Add upstream remote (usually the main repository)
~~~~{.c}
    git remote add upstream https://github.com/pgRouting/pgrouting
~~~~
   - check the remote connection
~~~~{.c}
    git remote -v
~~~~
   - Now you should have something like this:
~~~~{.c}
origin  https://github.com/acountName/pgrouting (fetch)
origin  https://github.com/acountName/pgrouting (push)
upstream        https://github.com/acountName/pgrouting (fetch)
upstream        https://github.com/acountName/pgrouting (push)
~~~~

@section branch_model Git Branching Model

We are making big efforts to start using the Git Branching Model
So here are some basic rules about Master and develop:
   - Pull requests against Master are almost never be accepted.
     - For micro changes
     - let us branch Master to a quick-fix branch
     - Merge into the quick-fix
     - We need to do some changes for the release numbers etc...
     - Finally we merge into Master
   - To accept a pull request into develop:
     - Its the same quick fix as for Master
     - It has to pass the tests on travis and Jenkins (linux & Windows)
     - Documentation must be "up to date"
     - Say that 99.9% is complete


The way we want to work:
   - If you want to work on a particular issue
     - Let us know creating an [issue](https://github.com/pgRouting/pgrouting/issues)
   - We will:
     - Create a branch derived from develop in the main repo that you can use in your fork
     - We will make the branch be checked on Travis
     - Your pull requests will be accepted (even with failures or incomplete)
     - We can help you with your work (remember it can have failures)
     - Once is stable we will start making tests on Jenkins
   - When the work is that 99.9% complete we can:
     - Merge into develop

For the rest of the document the following branch has being created in the main repository:

  dev-myFeature


1. To get a list of all the branches
  -
~~~~{.c}
   git branch -a
~~~~

2. To make sure you are in the correct branch
  -
~~~~{.c}
   git status
~~~~

3. When your forked before `dev-myFeature` was created
  - fetch the main repository
~~~~{.c}
   git fetch upstream
~~~~
  - get a list of your branches you should see the branch you are going to use:
~~~~{.c}
    git branch -a
    ...
    remotes/upstream/dev-myFeature
    ...
~~~~
  - go to your your local copy of the branch and push
~~~~{.c}
    git checkout dev-myFeature
    git push --set-upstream origin dev-myFeature
~~~~

4. Try new ideas in local branches, commit and merge back when you feel its worth to keep:
  - branch to a local branch
~~~~{.c}
    git checkout -b dev-myFeature-idea1
~~~~
  - Work, work, work
  - Always make sure you are in the branch you want to commit your work
~~~~{.c}
    git status
~~~~
  - add, delete, commit changes
~~~~{.c}
    git add <file>
    git remove <file>
    git mv <oldName> <newName>
    git commit -a -m '<commit message>'
~~~~

5. Merge back your ideas when you feel its worth to keep:
~~~~{.c}
    git checkout dev-myFeature
    git merge dev-myFeature-idea1
    <fix conflicts if any>
~~~~


@section up_to_date Keep Fork Up to Date

1. To keep your local repository up-to-date
~~~~{.c}
    git fetch upstream
~~~~

2. If you see changes in develop or master:
   - Commit your work
   - Update the branch that changed
~~~~{.c}
    git checkout develop
    git pull upstream
~~~~
   - Update your branch to include the change
~~~~{.c}
    git checkout dev-myFeature
    git merge develop
    <fix conflicts if any>
~~~~


@section perform_tests Beware of Side Effects

Modifications that you make should not affect other parts of the library.
pgRouting has a testing tool, for developers.

Make sure that
  - Code changes don't generate unexpected results
  - Bug fixes actually fix the bug
  - Expected output is generated

To do this:
1. Move to the root directory.
2. get the help of testing tool:
~~~~{.c}
     tools/testers/doc_queries_generator.pl -help
~~~~
3. run all the tests
~~~~{.c}
     tools/testers/doc_queries_generator.pl
~~~~

@section automate_process Make a run.sh

A shell to automate the compilation and execution is useful when developing.

1. Move to the root directory.

2. Create your tool:
~~~~{.c}
   vi run.sh
~~~~

3. Insert the usual process for creating and testing, for example:
~~~~{.c}
cd build/
#make clean
#rm -rf *
#cmake -DBOOST_ROOT:PATH=/usr/local/boost_1_58_0 ..
#cmake -DWITH_DOC=ON -DBUILD_DOXY ..
cmake ..

make

sudo make install
#make doc
#make doxy

cd ..

# before testing everything
tools/test-runner.pl -alg common
tools/test-runner.pl -alg dijkstra
tools/test-runner.pl -alg myfeature

# test everything
tools/test-runner.pl -alg
~~~~

4. Comment and uncomment the file depending on your particular needs and execute it.
~~~~{.c}
   sh run.sh
~~~~

@warning Don't add run.sh to the repository, its for your development only.


@section setup_travis Setup Travis

The main difference between your run.sh test and Travis test is:
  - With run.sh you are testing locally.
  - Travis tests a matrix combination of postgreSQL and postGIS versions

To make use of travis test make sure that:

1. Add your branch to  .travis.yml:
~~~~{.c}
branches:
  only:
    - master
    - develop
    - dev-myFeature
~~~~

2. Push your commit and navigate to [travis-ci](https://travis-ci.org)



@section file_convetions File conventions

Some conventions for directories and files
~~~~{.c}
/src/myfunction/doc/myfunction.rst ---> for myfunction wiki
/src/myfunction/sql/myfunction.sql ---> stored function code
/src/myfunction/test/myfunction.data ---> sql to generate test data
/src/myfunction/test/myfunction.test.sql ---> all possible myfunction usage
/src/myfunction/test/test.conf ---> perl file to test the function
/src/myfunction/CMakeLists.txt ---> CMake file
~~~~


*/