developer guide - cvvergara/pgrouting GitHub Wiki

intro_sec 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

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

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

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