7
7
How to develop for Fail2Ban
8
8
================================================================================
10
Fail2Ban uses GIT (http://git-scm.com/) distributed source control. This gives
11
each developer their own complete copy of the entire repository. Developers can
12
add and switch branches and commit changes when ever they want and then ask a
10
Fail2Ban uses GIT (http://git-scm.com/) distributed source control. This gives
11
each developer their own complete copy of the entire repository. Developers can
12
add and switch branches and commit changes when ever they want and then ask a
13
13
maintainer to merge their changes.
15
Fail2Ban uses GitHub (https://github.com/fail2ban/fail2ban) to manage access to
16
the Git repository. GitHub provides free hosting for open-source projects as
15
Fail2Ban uses GitHub (https://github.com/fail2ban/fail2ban) to manage access to
16
the Git repository. GitHub provides free hosting for open-source projects as
17
17
well as a web-based Git repository browser and an issue tracker.
19
If you are familiar with Python and you have a bug fix or a feature that you
20
would like to add to Fail2Ban, the best way to do so it to use the GitHub Pull
21
Request feature. You can find more details on the Fail2Ban wiki
19
If you are familiar with Python and you have a bug fix or a feature that you
20
would like to add to Fail2Ban, the best way to do so it to use the GitHub Pull
21
Request feature. You can find more details on the Fail2Ban wiki
22
22
(http://www.fail2ban.org/wiki/index.php/Get_Involved)
27
When submitting pull requests on GitHub we ask you to:
28
* Clearly describe the problem you're solving;
29
* Don't introduce regressions that will make it hard for systems adminstrators
31
* If adding a major feature rebase your changes on master and get to a single commit;
32
* Include test cases (see below);
33
* Include sample logs (if relevant);
34
* Include a change to the relevant section of the ChangeLog; and
35
* Include yourself in THANKS if not already there.
27
Existing tests can be run by executing `fail2ban-testcases`.
29
Documentation about creating tests (when tests are required and some guidelines
30
for creating good tests) will be added soon.
40
Existing tests can be run by executing `fail2ban-testcases`. This has options
41
like --log-level that will probably be useful. `fail2ban-testcases --help` for
44
Test cases should cover all usual cases, all exception cases and all inside
45
/ outside boundary conditions.
47
Test cases should cover all branches. The coverage tool will help identify
48
missing branches. Also see http://nedbatchelder.com/code/coverage/branch.html
51
Install the package python-coverage to visualise your test coverage. Run the
52
following (note: on Debian-based systems, the script is called
55
coverage run fail2ban-testcases
58
Then look at htmlcov/index.html and see how much coverage your test cases
59
exert over the codebase. Full coverage is a good thing however it may not be
60
complete. Try to ensure tests cover as many independent paths through the
63
Manual Execution. To run in a development environment do:
65
./fail2ban-client -c config/ -s /tmp/f2b.sock -i start
72
set test addaction iptables
73
set test actionban iptables echo <ip> <cidr> >> /tmp/ban
74
set test actionunban iptables echo <ip> <cidr> >> /tmp/unban
75
get test actionban iptables
76
get test actionunban iptables
77
set test banip 192.168.2.2
88
Please use tabs for now. Keep to 80 columns, at least for readable text.
93
Add tests. They should test all the code you add in a meaning way.
98
Test coverage should always increase as you add code.
100
You may use "# pragma: no cover" in the code for branches of code that support
101
older versions on python. For all other uses of "pragma: no cover" or
102
"pragma: no branch" document the reason why its not covered. "I haven't written
103
a test case" isn't a sufficient reason.
108
Ensure this documentation is up to date after changes. Also ensure that the man
109
pages still are accurate. Ensure that there is sufficient documentation for
110
your new features to be used.
115
Remove them and don't add any more.
120
Use the following tags in your commit messages:
123
'DOC:' for documentation fixes
124
'ENH:' for enhancements
125
'TST:' for commits concerning tests only (thus not touching the main code-base)
127
Multiple tags could be joined with +, e.g. "BF+TST:".
132
If you add an action.d/*.conf file also add a example in config/jail.conf
133
with enabled=false and maxretry=5 for ssh.
147
250
except FailManagerEmpty:
148
251
self.failManager.cleanup(MyTime.time())
150
thus channeling "ban tickets" from their failManager to a
253
thus channeling "ban tickets" from their failManager to the
151
254
corresponding jail.
156
259
Takes care about executing start/check/ban/unban/stop commands
265
# Check distribution patches and see if they can be included
267
* https://apps.fedoraproject.org/packages/fail2ban/sources
268
* http://sources.gentoo.org/cgi-bin/viewvc.cgi/gentoo-x86/net-analyzer/fail2ban/
269
* http://svnweb.freebsd.org/ports/head/security/py-fail2ban/
270
* https://build.opensuse.org/package/show?package=fail2ban&project=openSUSE%3AFactory
271
* http://sophie.zarb.org/sources/fail2ban (Mageia)
272
* https://trac.macports.org/browser/trunk/dports/security/fail2ban
274
# Check distribution outstanding bugs
276
* https://github.com/fail2ban/fail2ban/issues?sort=updated&state=open
277
* http://bugs.debian.org/cgi-bin/pkgreport.cgi?dist=unstable;package=fail2ban
278
* http://bugs.sabayon.org/buglist.cgi?quicksearch=net-analyzer%2Ffail2ban
279
* https://bugs.gentoo.org/buglist.cgi?query_format=advanced&short_desc=fail2ban&bug_status=UNCONFIRMED&bug_status=CONFIRMED&bug_status=IN_PROGRESS&short_desc_type=allwords
280
* https://bugzilla.redhat.com/buglist.cgi?query_format=advanced&bug_status=NEW&bug_status=ASSIGNED&component=fail2ban&classification=Red%20Hat&classification=Fedora
281
* http://www.freebsd.org/cgi/query-pr-summary.cgi?text=fail2ban
283
# Provide a release sample to distributors
285
* Debian: Yaroslav Halchenko <debian@onerussian.com>
286
http://packages.qa.debian.org/f/fail2ban.html
287
* FreeBSD: Christoph Theis theis@gmx.at>, Nick Hilliard <nick@foobar.org>
288
http://svnweb.freebsd.org/ports/head/security/py-fail2ban/Makefile?view=markup
289
* Fedora: Axel Thimm <Axel.Thimm@atrpms.net>
290
https://apps.fedoraproject.org/packages/fail2ban
291
* Gentoo: netmon@gentoo.org
292
http://sources.gentoo.org/cgi-bin/viewvc.cgi/gentoo-x86/net-analyzer/fail2ban/metadata.xml?view=markup
293
* openSUSE: Stephan Kulow <coolo@suse.com>
294
https://build.opensuse.org/package/users?package=fail2ban&project=openSUSE%3AFactory
295
* Mac Ports: @Malbrouck on github (gh-49)
296
https://trac.macports.org/browser/trunk/dports/security/fail2ban/Portfile
298
# Wait for feedback from distributors
300
# Ensure the version is correct in ./common/version.py
302
# Add/finalize the corresponding entry in the ChangeLog
304
To generate a list of committers use e.g.
306
git shortlog -sn 0.8.8.. | sed -e 's,^[ 0-9\t]*,,g' | tr '\n' '\|' | sed -e 's:|:, :g'
308
Ensure the top of the ChangeLog has the right version and current date.
310
Ensure the top entry of the ChangeLog has the right version and current date.
314
(cd man ; ./generate-man )
315
git commit -m 'update man pages for release' man/*
317
# Make sure the tests pass
319
./fail2ban-testcases-all
321
# Prepare/upload source and rpm binary distributions
323
python setup.py check
324
python setup.py sdist
325
python setup.py bdist_rpm
326
python setup.py upload
328
# Run the following and update the wiki with output:
330
python -c 'import common.protocol; common.protocol.printWiki()'
332
# Email users and development list of release
334
# notify distributors
339
Add the following to the top of the ChangeLog
341
ver. 0.8.9 (2013/XX/XXX) - wanna-be-stable
added
removed
DEVELOP
