First steps for a new developer

The objective of this small tutorial is to show to edit netzob's main source code.
In this tutorial we consider the followings :

Configure your environment

Step 1 : Configure your environment through git configuration

git config --global user.name "Robert Patate" 
git config --global user.email robert.patate@parmentier.com

Step 2 : Download your developer repository

git clone netzob@dev.netzob.org:people/rpatate/netzob netzob-rpatate

A directory should be created named "netzob-rpatate"

Step 3 : Move into the local repository

cd netzob-rpatate

Step 4 : Register the remote repository of the officials sources of Netzob (to stay up-to-date)

git remote add netzob https://dev.netzob.org/git/netzob.git

Step 5 : You retrieve its content

git pull netzob master

Now if you list your repository you should see the latest source codes

Step 6 : Apply pre-commit hook
See Prevent pushing mistakes using dedicated commit hooks

Start developing

To explain the workflow we'll take a simple example.
You have found an invalid menu entry named 'Display Console' which you think must be removed since its useless.

Step 1 : Open a dedicated defect ticket
The first step in this process is to explain to the team what you want to do. To do so open a ticket using the form at https://dev.netzob.org/projects/netzob/issues/new and
fill the mandatory fields which are :

  • Tracker : select "Defect" if its a bug, "Feature" if your proposition will add a new feature.
  • Subject : a short description of the operation
  • Description : a full description of the problem and of the solution you propose.

In our case, we fill with the followings :

  • Tracker : Defect
  • Subject : Remove useless 'display console' menu entry
  • Description : *The submenu 'View' of the main menu contains a deactivated entry named 'Display console'.

This entry is useless and therefore should be removed.
It should be re-introduced when the associated feature will be available.*

Once fulfilled, we can create the ticket and remember its number. In our case, the ticket number is #185 and appears in the 'todo-list'.
The creation of your ticket has automatically fired an email notification on the dev-list.
If you need help or advices, you can use the mailing list or IRC and refers to your proposition with the ticket number.
You can also comment your ticket with additional information which concerns this task.

Step 2 : Starting the development
The first step will be ensure your source repository is up-to-date :

gbossert@laptop:~/Developpements/GITRepositories/netzob-gbossert$ git pull netzob master
From https://dev.netzob.org/git/netzob
 * branch            master     -> FETCH_HEAD
Already up-to-date.

Once you've synchronized your repository, you can create a dedicated branch which will host your modifications. In our case, we name our branch 'removeUselessEntryMenu'.

gbossert@laptop:~/Developpements/GITRepositories/netzob-gbossert$ git checkout -b "removeUselessEntryMenu" 
Switched to a new branch 'removeUselessEntryMenu'

If you want to verify you're in the right place to work on this feature, you can use the following command to list available branch (the current one is highlighted) :

gbossert@laptop:~/Developpements/GITRepositories/netzob-gbossert$ git branch
  master
* removeUselessEntryMenu

Step 3 : Modifying the source code

Now you can start to modify the source code.
Don't forget to build the project in order to be able to execute it and to verify Netzob is still 'working' :

gbossert@laptop:~/Developpements/GITRepositories/netzob-gbossert$ python setup.py build
[...]
gcc -pthread -shared -Wl,-O1 -Wl,-Bsymbolic-functions build/temp.linux-i686-2.7/lib/libNeedleman/libNeedleman.o -o build/lib.linux-i686-2.7/_libNeedleman.so
running build_scripts
creating build/scripts-2.7
copying and adjusting netzob -> build/scripts-2.7
changing mode of build/scripts-2.7/netzob from 644 to 755
running build_manpage

When you've finished to modify the source code, you can prepare the commit. For this, you have to "stage" the modify files. Only "staged" files will be included in a commit.

gbossert@laptop:~/Developpements/GITRepositories/netzob-gbossert$ git status
# On branch removeUselessEntryMenu
# Changes not staged for commit:
#   (use "git add <file>..." to update what will be committed)
#   (use "git checkout -- <file>..." to discard changes in working directory)
#
#    modified:   src/netzob/Common/Menu.py
#
no changes added to commit (use "git add" and/or "git commit -a")

We can see that I've only modified the Menu.py file. To add it (meaning to stage it), I execute the following command:

gbossert@laptop:~/Developpements/GITRepositories/netzob-gbossert$ git add src/netzob/Common/Menu.py

When ready, I create a commit with the following command :

gbossert@laptop:~/Developpements/GITRepositories/netzob-gbossert$ git commit
[I] Retrieve all the files to analyze.
[I] 1 files will be analyzed.
[I] File src/netzob/Common/Menu.py:
[E]     PEP8 : src/netzob/Common/Menu.py:214:9: E303 too many blank lines (2)
[E]     PEP8 : src/netzob/Common/Menu.py:548:52: E203 whitespace before ':'
[E] Errors founds, commit not allowed.

An error occurred and I'm not allowed to commit because the file 'menu.py' contains PEP8 errors I first fix. Once fixed, I re-add the new modifications with the command :

gbossert@laptop:~/Developpements/GITRepositories/netzob-gbossert$ git add src/netzob/Common/Menu.py

And i can commit :

gbossert@laptop:~/Developpements/GITRepositories/netzob-gbossert$ git commit
[I] Retrieve all the files to analyze.
[I] 1 files will be analyzed.
[I] File src/netzob/Common/Menu.py:
[I]     no error found.
[I] No error found, commit allowed.
[removeUselessEntryMenu c32d3ab] Remove useless 'display console' menu entry (IssueID #185).
 1 files changed, 0 insertions(+), 7 deletions(-)

The message commit I've entered contains a short description (the first line), a reference to the ticket (IssueID #...) and a detailed description.

I can verify the commit with the command git log :

git log -1
commit c32d3ab10c2086f816a10d88d56ff93ea4715a83
Author: Georges Bossert <georges.bossert@supelec.fr>
Date:   Tue Apr 17 16:02:55 2012 +0200

    Remove useless 'display console' menu entry (IssueID #185).

    The mani menu contains an entry which refers to the console. This feature
    is not yet available therefore the menu should not reference it.

Step 3 : Editing my commit message
I've done a small mistake in the commit message. To change it, I will create a new "amending" commit which will fix the previous one :

gbossert@laptop:~/Developpements/GITRepositories/netzob-gbossert$ git commit --amend
[I] Retrieve all the files to analyze.
[I] 0 files will be analyzed.
[I] No error found, commit allowed.
[removeUselessEntryMenu d3da0de] Remove useless 'display console' menu entry (IssueID #185).
 1 files changed, 0 insertions(+), 7 deletions(-)

Step 4 : Make your commit publicly available
In order to publish your branch on the repository, use the following command :

gbossert@laptop:~/Developpements/GITRepositories/netzob-gbossert$ git push origin removeUselessEntryMenu
Counting objects: 1761, done.
Delta compression using up to 4 threads.
Compressing objects: 100% (871/871), done.
Writing objects: 100% (1568/1568), 193.25 KiB, done.
Total 1568 (delta 1013), reused 808 (delta 513)
To netzob@dev.netzob.org:people/gbossert/netzob
 * [new branch]      removeUselessEntryMenu -> removeUselessEntryMenu

Step 5 : Prepare the pull-request
To do a pull-request, we need to identify the list of commits we want to push. This can be done we the simple command :

gbossert@laptop:~/Developpements/GITRepositories/netzob-gbossert$ git log --pretty --format=oneline -5
cf0e7278c706e77b22bf4e09cfae8594df424480 Cleaning the file
d3da0deeaa4cc727081491b97bdb3fc7a2d21cc4 Remove useless 'display console' menu entry (IssueID #185).
c54d3a260163b128a6e18efa92d6bb16d13ee27c Merge branch 'master' of dev.netzob.org:netzob
8b41d2d13c230b12dfd5f91e2f2d40fc6921c948 Offer a second manual attempt to the user when loading the workspace (closes #116).
6674e2dc38331ce848f1d0989877a1d80ea06719 Reverse the static resources loading order.

Following this list, we decide to start at commit c54d3a260163b128a6e18efa92d6bb16d13ee27c and to finish at commit cf0e7278c706e77b22bf4e09cfae8594df424480.
Hence, the text of the pull-request can be obtained using the following command :

gbossert@laptop:~/Developpements/GITRepositories/netzob-gbossert$ git request-pull c54d3a260163b128a6e18efa92d6bb16d13ee27c origin cf0e7278c706e77b22bf4e09cfae8594df424480
The following changes since commit c54d3a260163b128a6e18efa92d6bb16d13ee27c:

  Merge branch 'master' of dev.netzob.org:netzob (2012-04-17 12:21:57 +0200)

are available in the git repository at:

  netzob@dev.netzob.org:people/gbossert/netzob removeUselessEntryMenu

for you to fetch changes up to cf0e7278c706e77b22bf4e09cfae8594df424480:

  Cleaning the file (2012-04-17 17:14:58 +0200)

----------------------------------------------------------------
Georges Bossert (2):
      Remove useless 'display console' menu entry (IssueID #185).
      Cleaning the file

 src/netzob/Common/Menu.py |   10 +---------
 1 files changed, 1 insertions(+), 9 deletions(-)

Step 6: Publishing your pull-request

The last step is to open "pull-request" ticket using the form at https://dev.netzob.org/projects/netzob/issues/new with the following informations :
  • Tracker : Pull-Request
  • Subject : Fix for defect #185
  • Description : <the content of the pull request obtained in step 5>.

Pushing your modifications on the official repository

Like multiple other opensource project, Netzob is organized around a community-based validation process for new commits.
It means you submit your modifications, others review them and if its ok, your modifications and metadatas associated (date, author names, ...) are copied on the official repository.
Hence, the first step to provide your modifications is to publish a "Pull Request" using "New issue" formular (select the appropriate tracker).
The description of this Pull Request should contains the result of following command :

git request-pull master origin

Extras

To modify the description of your private repository

echo "Robert Patate's netzob repository" | ssh netzob@dev.netzob.org setdesc people/rpatate/netzob

Also available in: PDF HTML TXT