Merge pull request #53 from balabit/gsoc-fixes

GsoC fixes

SUMMARY.md

@@ -12,7 +12,7 @@
     * [fetching dependencies](chapters/chapter_2/section_1.md)
     * [compile](chapters/chapter_2/section_2.md)
     * [testing](chapters/chapter_2/section_3.md)
-    * [cleanup](chapters/chapter_2/section_4.md)
+    * [install](chapters/chapter_2/section_4.md)
 * [run first](chapters/chapter_3/README.md)
     * [write your first config](chapters/chapter_3/section_1.md)
     * [syslog-ng](chapters/chapter_3/section_2.md)

chapters/chapter_0/section_1.md

@@ -18,6 +18,7 @@ The syslog-ng team has an unofficial APT repository hosted by OBS for Debian and
 Available versions in the OBS repository :
  * 3.6.4
  * 3.7.1
+ * 3.7.2
 
 The packaging structure following the original one was created by algernon for Debian systems.
 This is basically a modular packaging strategy.

chapters/chapter_1/README.md

@@ -4,7 +4,3 @@ In this chapter we are going to introduce you the project and repository archite
 to develop syslog-ng. Understanding these basics is crucial before starting your contribution 
 to the project. Without speaking the same language on structure of development the project can
 get easily obfuscated that makes further contribution impossible.
-
-If you lack something (or something is not clear enough) after reading this chapter, 
-[please contact](https://waffle.io/balabit/syslog-ng-gitbook) to help us improve the usability of this book.
-

chapters/chapter_1/section_1.md

@@ -1,5 +1,9 @@
-{% extends "templates/error_under_constr.md" %}
-{% block title %}
-# project structure
-{% endblock %}
+# Project structure
 
+The following directories are the most substantial ones:
+
+* `lib/`: common source code used by syslog-ng
+* `modules/`: each module in syslog-ng has a directory here, like `redis`
+* `syslog-ng`: the source code of the `syslog-ng` binary
+* `syslog-ng-ctl`: the source code of the `syslog-ng-ctl` command line utility
+* `tests`: the home of unit tests and functional tests (but there are tests next to their tested functionality)

chapters/chapter_1/section_2.md

@@ -1,6 +1,6 @@
 # Git structure
 
-When a lot of people contribute on the same project it is impossible not to use 
+When a lot of people contribute on the same project it is impossible not to use
 some kind of version control system to track the evolution of the development.
 Because we love open source solutions and use GitHub to publish our code it was 
 natural to use Git as a version control system. 
@@ -16,27 +16,20 @@ according to branching and naming conventions, though.
 ## Branching
 
 ### master
-Master stands for the absolute upstream. Main branch of the repository.
-
-### f/loremipsum
-* **f:** represents that it is a feature or fix branch that adds a new feature or fixes a bug
-* **loremipsum:** short name of the content of the branch
-
-_example (feauture)_: f/templatable-recipients
-
-_example (bug)_: f/memleak-in-queueing
+Master stands for the absolute upstream, most of the development happens on this branch. If you
+want to contribute a new feature of you should send your Pull Request against this branch.
 
 ### X.X/master
 Older version of the project.
 
-X.X stands for a version number 3.5/3.6/3.7 of the project. 
-
-_example_: 3.6/master
-
-### X.X/f/loremipsum
-Feature or bugfix branch for an older version of the project.
+X.X stands for a version number 3.5/3.6/3.7 of the project. These branches receive mostly
+bug fixes.
 
-X.X stands for a version number 3.5/3.6/3.7 of the project. 
+_example_: 3.7/master
 
-_example (bug)_: 3.6/f/memleak-in-queueing
+### loremipsum
+Every other branch either adds a new feature of fixes a bug. We used to prefix all feature
+branches with `f/` but we no longer maintain this practice.
 
+If you send a bug fix, use the `fix-` prefix, like `fix-memleak-in-queueing`. If you implemented a new feature,
+use some descriptive name for your branch, like `add-kafka-destination`.

chapters/chapter_2/README.md

@@ -1,5 +1,6 @@
-{% extends "templates/error_under_constr.md" %}
-{% block title %}
-# compile first
-{% endblock %}
+# Compile first
 
+This chapter describes the building and testing process of syslog-ng.
+
+If you want to develop syslog-ng, you should be familiar with building syslog-ng
+from source.

chapters/chapter_2/section_1.md

@@ -7,7 +7,7 @@
 [ref:libtool]: http://www.gnu.org/software/libtool/
 [ref:automake]: http://www.gnu.org/software/automake/
 [ref:bison]: http://www.gnu.org/software/bison/
-[gh:eventlog]: http://github.com/eldarion/eventlog
+[gh:eventlog]: https://github.com/balabit/eventlog
 [ref:pcre]: http://www.pcre.org
 [gh:ivykis]: http://github.com/buytenh/ivykis
 [gh:json-c]: http://github.com/json-c/

chapters/chapter_2/section_2.md

@@ -1,5 +1,58 @@
-{% extends "templates/error_under_constr.md" %}
-{% block title %}
-# compile
-{% endblock %}
+# Compiling
 
+This description demonstrates the building steps on the upstream repository, but you can apply these steps
+on your forked repository as well.
+
+## Building
+
+1. Clone your forked repository locally
+
+ ```
+git clone https://github.com/balabit/syslog-ng.git
+```
+
+2. Step into the directory `syslog-ng` directory and run `autogen.sh`:
+
+ ```
+./autogen.sh
+```
+
+ This script will clone the Git submodules and initialize the build system. The
+result of the execution should be a `configure` script.
+
+3. Create build directory
+We prefer to build syslog-ng in a dedicated directory, so your Git repo is kept
+tidy.
+
+ ```
+mkdir build
+cd build
+```
+
+4. Run the `configure` scipt:
+
+ ```
+../configure --enable-debug --prefix=$HOME/install/syslog-ng
+```
+
+ You can pass additional parameters to configure, but these are the most common ones.
+If you run `../configure --help` you can see all the valid parameters.
+The result of the configuration process is several new `Makefile`s in your build directory.
+
+5. Run `make`:
+
+ ```
+make -j
+```
+
+ The `-j` flag will parallelize the compilation process. If `make` works for you (without `-j`),
+but `make -j` does not, that is a bug.
+
+### Expected outcome ###
+
+You should have a freshly built syslog-ng by the end of this step.
+
+## Cleanup
+
+ You can execute `make clean` to remove the build artifacts. `make distclean` will also
+remove the `configure` script. You can also completely remove the content of your build directory.

chapters/chapter_2/section_3.md

@@ -1,4 +1,28 @@
-{% extends "templates/error_under_constr.md" %}
-{% block title %}
-# testing
-{% endblock %}
+# Testing
+
+## The make check command
+
+Run `make check`. This will compile and execute the unit
+tests. If everything is OK, you should see something like this:
+
+```
+============================================================================
+Testsuite summary for syslog-ng 3.8.0alpha0
+============================================================================
+# TOTAL: 82
+# PASS:  82
+# SKIP:  0
+# XFAIL: 0
+# FAIL:  0
+# XPASS: 0
+# ERROR: 0
+============================================================================
+```
+
+If something goes wrong, check the logs of the tests (`test-suite.log`). You can debug
+the failing unit test with a debugger.
+
+## The make distcheck command
+
+The `make distcheck` command is very similar to `make check`, but it also ensures that
+the distribution tarball can be properly used.

chapters/chapter_2/section_4.md

@@ -1,4 +1,4 @@
-{% extends "templates/error_under_constr.md" %}
-{% block title %}
-# cleanup
-{% endblock %}
+# Install
+
+You can install your freshly built syslog-ng with `make install`. Note that
+the files will be copied under `$prefix` (what you have set for `configure` with `--prefix=`).