Introduction

This documentation is focused on the developer of pgRouting.

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 wirtten by Mohamed Zia
Git Branch Model

Installation for developing

Step by Step processing

Create a fork of the original pgRouting repository.
- If you don't have an account in Github, please create one
  - for purposes of this document the account name is: acountName
- Navigate to pgRouting repository.
- In the top-right corner of the page, click Fork.
- Additional information can be found in fork-a-repo
Now create a local clone of your above created fork
- set up Git in your computer.
- clone your repo
  git clone https://github.com/acountName/pgrouting pgrouting
Go to your repo
cd pgrouting
Setting the remote fetching connections
- More on remotes .
- check the remote connection
  git remote -v
- Add upstream remote (usually the main repository)
  git remote add upstream https://github.com/pgRouting/pgrouting
- check the remote connection
  git remote -v
- Now you should have something like this:
  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)

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
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

To get a list of all the branches
- git branch -a
To make sure you are in the correct branch
- git status
When your forked before dev-myFeature was created
- fetch the main repository
  git fetch upstream
- get a list of your branches you should see the branch you are going to use:
  git branch -a
  
  ...
  
  remotes/upstream/dev-myFeature
  
  ...
- go to your your local copy of the branch and push
  git checkout dev-myFeature
  
  git push --set-upstream origin dev-myFeature
Try new ideas in local branches, commit and merge back when you feel its worth to keep:
- branch to a local branch
  git checkout -b dev-myFeature-idea1
- Work, work, work
- Always make sure you are in the branch you want to commit your work
  git status
- add, delete, commit changes
  git add <file>
  
  git remove <file>
  
  git mv <oldName> <newName>
  
  git commit -a -m '<commit message>'
Merge back your ideas when you feel its worth to keep:
git checkout dev-myFeature

git merge dev-myFeature-idea1

<fix conflicts if any>

Keep Fork Up to Date

To keep your local repository up-to-date
git fetch upstream
If you see changes in develop or master:
- Commit your work
- Update the branch that changed
  git checkout develop
  
  git pull upstream
- Update your branch to include the change
  git checkout dev-myFeature
  
  git merge develop
  
  <fix conflicts if any>

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:

Move to the root directory.
get the help of testing tool:
tools/testers/doc_queries_generator.pl -help
run all the tests
tools/testers/doc_queries_generator.pl

Make a run.sh

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

Move to the root directory.
Create your tool:
vi run.sh
Insert the usual process for creating and testing, for example:
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
Comment and uncomment the file depending on your particular needs and execute it.
sh run.sh

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

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:

Add your branch to .travis.yml:
branches:

only:

- master

- develop

- dev-myFeature
Push your commit and navigate to travis-ci

File conventions

Some conventions for directories and files

/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