Github work flow¶

Suricata's development is done using Git and Github. While it is possible to not use Github, we highly recommend it as Github has great review tools.

Forking the github repo¶

In github, go to https://github.com/OISF/suricata and click the "fork" button. Yes, it's that easy.

Cloning your suricata fork to edit it¶

You can follow instruction provided on github page. Basically, you set your username and clone the git repository:

git clone https://github.com/<username>/suricata.git

Enter the new "suricata" directory. You'll be in the master branch.

Creating a branch to do your changes¶

git checkout master -b <your branch name>

Committing your changes¶

git add <changed file(s)>
git commit

Your favorite editor will be run and you be able to write a meaningful commit message. Don't forget this is an information for the reviewer and a reference for future development.

or if you just want to commit all your local changes

git commit -a

Pushing your branch to your github repo¶

Once your happy with your branch, you can push it to github:

git push origin <your branch name>

Creating a pull request¶

To get your changes included in the official branch you need to create a pull request.

To do so, go to your fork page on github and choose the branch you want to merge in the menu.

Once done, click the Pull request button at the top of the page.
You will then be able to choose the branch on which you want to do the pull request.

Create a new branch for incorporating feedback¶

After doing the pull request, do not update the branch anymore. If you need to do changes, create a new branch (see amending commits)

For a lengthy discussion on why pull request shouldn't be updated, see https://github.com/torvalds/linux/pull/17#issuecomment-5654674

In short, a pull request is a link to a branch, not a specific commit. Updating the branch after doing the pull request breaks the review process and also messes up the comments that may be part of the review process.

Incorporating feedback¶

If the pull request wasn't merged directly, it's probably because there is some feedback that needs to be processed.

Rebasing to current upstream master¶

To do so, you need to indicate to git that the OISF repository is the upstream repo.

git remote add upstream https://github.com/OISF/suricata.git

Then you can fetch the data and rebase your local branch:

git fetch
git pull upstream --rebase master

Amending commits¶

One possible workflow consist in creating a new branch to incorporate the modifications asked during the review.

git checkout -b <your-branch-name-v2> <your-branch-name-v1>

You can then incorporate the needed modifications with respect to their initial commit. To do so, you can do small commit and use git rebase to merge them:

git rebase -i upstream/master

After creating the second improved branch push it and create a new pull request(PR). Please close the old PR, link to it and state the improvement changes in the description of the new PR.

An Example¶

Let see an example, by running git rebase -i upstream/master, we can have the editor started and displaying something like the following:

pick bfd6dea pool: update doxygen documentation.
pick 84e0d76 doxygen: generate doc for acquisition modules
pick b0a2aef af-packet: fix build on systems without AF_PACKET
pick 2a21e36 decode: use pointer inside packet area as param
pick dc9f524 WIP: FIX af-packet: fix build
pick fe2907c WIP: FIX pool: update doxygen

We've got two commits at the end which are fixes for the previous one. So, the only thing we need to do is to move them just after the commit they update and set the start letter to 'f' like fix:

pick bfd6dea pool: update doxygen documentation.
f fe2907c WIP: FIX pool: update doxygen
pick 84e0d76 doxygen: generate doc for acquisition modules
pick b0a2aef af-packet: fix build on systems without AF_PACKET
f dc9f524 WIP: FIX af-packet: fix build
pick 2a21e36 decode: use pointer inside packet area as param

Now, you just have to save and quit, to see:

[detached HEAD 2c8c540] pool: update doxygen documentation.
 2 files changed, 33 insertions(+)
[detached HEAD 057b6d9] af-packet: fix build on systems without AF_PACKET
 2 files changed, 3 insertions(+), 1 deletion(-)
Successfully rebased and updated refs/heads/demo.

One other solution to update commit is to rebase and indicate that some commits need to be edited.
After git rebase -i upstream/master, you will edit the buffer:

e bfd6dea pool: update doxygen documentation.
pick 84e0d76 doxygen: generate doc for acquisition modules
e b0a2aef af-packet: fix build on systems without AF_PACKET
pick 2a21e36 decode: use pointer inside packet area as param

After saving, you will see:

Stopped at 2c8c540... pool: update doxygen documentation.
You can amend the commit now, with

    git commit --amend

Once you are satisfied with your changes, run

    git rebase --continue

You can make the needed modification on the file, run git add <changed file(s) followed by git commit --amend to update the commit. Then run git --rebase continue to jump to next edit.

Please note that your best friend here is: git rebase --abort which will restore the initial state.