Developer Guide - pgRouting/pgrouting GitHub Wiki

• Introduction
• Installation for developing
• Git branching model
  • Some git commands
• File conventions

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

Installation for developing

Step by Step processing

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

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

3. Go to your repo

cd pgrouting

4. 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 CI tests
• 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 Work on your fork:
• Create a branch derived from develop
• We can help you with your work
  • let us know your fork and branch
  • Communicate on pgrouting-dev Prepare your PR
• Create a branch that derived from develop that will contain your changes
• make commits by directory
  • git checkout files from your work branch by directory
• Merge into develop

some basic git commands

1. To get a list of all the branches

git branch -a

2. To make sure you are in the correct branch

git status

3. create a branch based on develop

git fetch upstream
git checkout upstream/develop
git switch -c myFeature-idea1

5. Always make sure you are in the branch you want to commit your work

git status

Keep Fork Up to Date

1. To keep your local repository up-to-date

git fetch upstream

2. If you see changes in develop or master:
   • Commit your work
   • Update the branch that changed

git checkout 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 documentation queries can be used as a "naive" testing tool.

To do this:

1. Move to the root directory.

tools/testers/doc_queries_generator.pl -help

3. Compare old results with new results

tools/testers/doc_queries_generator.pl

Make a shell script

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

1. Move to the root directory.
2. Create your tool say myscript.sh:

vi myscript.sh

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

# Compare the documentation queries
tools/testers/doc_queries_generator.pl -alg dijkstra
tools/testers/doc_queries_generator.pl -alg myfeature

4. Comment and un-comment the file depending on your particular needs and execute it.

bash myscript.sh

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

File conventions

Some conventions for directories and files: Keep your work on same subdirectories

doc/foo/pgr_myfunction.rst  
sql/foo/myfunction.sql       
sql/foo/_myfunction.sql       
src/foo/myfunction.c

doc/foo/test.conf
doc/foo/myfunction/CMakeLists.txt
doc/foo/myfunction.pg 
doc/foo/myfunction.result

We are moving forward to standardize some common functions

src/foo/myfunction_driver.cpp 

OR the standardized version

src/foo/foo_driver.cpp
src/foo/foo_process.cpp