My Experience with GitHub
The real feeling of being a FOSS4G developer is missing if have not contribute any knowledge to the open-community. I came to know about pgRouting 1.5 years ago and since then am trying to do understand it fully and alter for special scenarios. At the beginning I was following gis.stackexchange to learn its usage among the community but later on started following github repo. The dynamic albeit small developer community of pgRouting is quite friendly which gave me a chance to express myself and ideas at different occasions. Recently I was able to successfully propose and merge own custom function into the package for 2.2 release, hopefully.
I would like to share some of my experience and knowledge which I gathered during the whole process.
Questions before which I always had:
Q1. My idea sounds crap.
Q2. Where shall I go to get some feedback?
Q3. My codes does not look perfectly designed.
Q4. How to deal with this GitHub monster?
What I did
A1. Do some RnD on web-forums to see if there is already a solution or not. But don't waste too much time. Better to dwell into it. But listening to your intuition is also important.
A2. Searched and posted my idea on gis.stackexchange to see what other people of similar interest has to say about it.
A3. Don't worry about the perfect. Even proprietary packages also keep on releasing improved versions to incorporate best practices and recent developments.
A4. Take some very basic online lessons on git to understand basic idea. I found link to be highly informative. Git-Branching-Model printout is always on my office table. Besides, don't worry, other developers will guide you through the process. This is the power of community effort.
How to contribute I you have something really solid?
Create an issue on pgRouting repo about your idea and let the discussion start.
Step by Step processing
-
Create a fork of the original repo from your GitHub account.
-
Now create a local clone of your above created fork git clone https://github.com/Zia-/pgrouting pgrouting
-
Check remote fetching connections git remote -v
-
Adding upstream connections git remote add upstream https://github.com/pgRouting/pgrouting
-
To get a list of all the branchs git branch -a
-
To keep your local develop repo up-to-date (for this command step 4 is a must). This command will update local repo wrt to the original repo present at the upstream. git fetch upstream
-
After above command you will see all the branchs (present in your fork (origin) or in the main repo (upstream)) into ur local repo. Ex remotes/origin/develop remotes/upstream/develop
-
To check which branch u r currently in git status --On branch develop --Your branch is up-to-date with 'origin/develop'.
-
Make a new branch from your origin/develop branch in order to work for let's say a feature git checkout -b pgr_projectNodeAndSplitEdge
-
In case u want a branch from some other branch (like upstream/develop rather than origin/develop). git checkout upstream/develop git checkout -b pgr_projectNodeAndSplitEdge
-
Check current working branch. Depending upon current brach, folders inside the directory will appear and disappear. git status
-
How to perform run.sh test?
-
The difference between run.sh test and Travis test is that in the initial one you are testing for broken package locally. Travis is more robust testing and provides all combinations of postgreSQL and postGIS versions.
-
Move to a directory and add a file cd /etc/label_graph/sql gedit project_node_and_split_edge.sql
-
In case you want to rename the above newly created file mv project_node_and_split_edge project_node_and_split_edge.sql
-
If git is already tracking that file (you have already done git add) then rename like this git mv project_node_and_split_edge project_node_and_split_edge.sql
-
Now track all the untracked files. First check untracked files git status git add project_node_and_split_edge
-
Check again if the untracked files are now getting tracked. git status
-
Git commit (-a will keep a track of all the modifications done) git commit -a -m "Added a new file"
-
Git push to push all the changes and new branch to your origin repo (not the remote, for remote u have to create a pull request and then the author of the remote will decide whether to merge or not) git push OR git push --set-upstream origin pgr_projectNodeAndSplitEdge
-
How to use git pull?
-
One can add a new function at the following places depending upon the usage /src/common/ OR /src
-
If one is making a separate directory for his/her function then add the following 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
-
Add about your proposed function at package index.rst file /doc/index.rst
-
One can also add the branch name into travis file so that travis test will start running the moment there will be a push operation. Simple edit ".travis.yml" file at the root directory by adding your branch name. branches: only: - master - develop - develop_2_1_0 - feature-travis - dd-develop - your-branch
