Contributing¶
Bug Reporting¶
Please report any bugs in the Launchpad tracker. (Oh, and check for existing ones that match your problem first.)
Good bug reports describe the problem, include the message to the bot
that caused the bug, and any logging information / exceptions from
ibid.log
.
Submitting Patches¶
Want to go one step further, and fix your bug or add a new feature. We welcome contributions from everyone. The best way to get a patch merged quickly is to follow the same development process as the Ibid developers:
If you don’t have one, create a Launchpad account and configure Bazaar to use it.
If there isn’t a bug in the tracker for this change, file one. It motivates the change.
Mark the bug as In Progress, assigned to you.
Take a branch of Ibid trunk (See Bazaar for Ibid Developers if you are new to Bazaar):
user@box $ bzr branch lp:ibid description-1234
description
is a two or three-word hyphen-separated description of the branch,1234
is the Launchpad bug number.Fix your bug in this branch, following the Style Guidelines. See also Running a Development Ibid.
Link the commit that fixes the bug to the launchpad bug:
user@box $ bzr commit --fixes lp:1234
Test that the fix works as expected and doesn’t introduce any new bugs.
pyflakes
can find syntax errors you missed.Run the test-cases:
user@box $ trial ibid
Push the branch to Launchpad:
user@box $ bzr push lp:~yourname/ibid/description-1234
Find the branch on Launchpad and propose it for merging into the Ibid trunk.
Proposals require approvals by a member of ibid-core and two members of ibid-dev (or simply two members of ibid-core).
Please join ibid-dev and help out with review.
Style Guidelines¶
Writing code that matches the Ibid style will lead to a consistent code base thus happy developers.
- Follow PEP 8, where it makes sense.
- 4 space indentation.
- Single quotes are preferred to double, where sensible.
- Almost all of Ibid should be compatible with Python 2.4+ (but not 3).
Compatibility functions, imports, and libraries can be found in
ibid.compat
. - There is more on good style in Code Like a Pythonista: Idiomatic Python.
Naming Conventions¶
- Features should either go into an existing plugin, or if large enough into a plugin of the same name as the feature (singular).
- Database table names are plural.
Sources¶
- Follow Twisted style.
Plugins¶
- All features should have help and usage strings.
- Try to code for the general case, rather than your specific problem.
Option
configurables are handy for this, but don’t bother making things that will never be changed configurable (i.e. static API endpoints). - Use
event.addresponse
‘s string formatting abilities where possible. This will aid in future translation. - Any changes to database schema should have upgrade-rules included for painless upgrade by users.
- Write tests for your code at
ibid/test/plugins/test_pluginname.py
. Theibid.test
module provides an API for testing plugins.
Bot Responses¶
- While there are exceptions, a well behaved Ibid only speaks when spoken to.
- URLs should be surrounded with whitespace to help clients detect them.
Bazaar for Ibid Developers¶
You’ll want a non-ancient version (>=1.16) of Bazaar (check your distribution’s backport repository), and a Launchpad account.
If you’ve never used Bazaar before, read Bazaar in five minutes.
Configure Bazaar to know who you are:
~ $ bzr whoami "Arthur Pewtey <apewtey@example.com>"
~ $ bzr launchpad-login apewtey
Make a Bazaar shared repository to contain all your Ibid branches:
~ $ mkdir ~/code/ibid
~ $ cd ~/code/ibid
~/code/ibid $ bzr init-repo --2a .
Check out Ibid trunk:
~/code/ibid $ bzr checkout lp:ibid trunk
When you wish to create a new branch:
~/code/ibid $ bzr update trunk
~/code/ibid $ bzr branch trunk feature-1234
If you want to easily push this to Launchpad, create a
~/.bazaar/locations.conf
with the following contents:
[/home/apewtey/code/ibid]
pull_location = lp:~apewtey/ibid/
pull_location:policy = appendpath
push_location = lp:~apewtey/ibid/
push_location:policy = appendpath
public_branch = lp:~apewtey/ibid/
public_branch:policy = appendpath
That will allow you to push your branch to
lp:~apewtey/ibid/feature-1234
by typing:
~/code/ibid/feature-1234 $ bzr push
To delete a branch, you can simply rm -r
it.
See also:
Running a Development Ibid¶
A full-blown Ibid install is overkill for development and debugging cycles.
Ibid source contains a developer-oriented ibid.ini
in the root
directory.
This uses SQLite and connects to a South African IRC server.
If you wish to change it, either remember not to commit this file to
your branch, or override settings in local.ini
, which is ignored by
Bazaar.
Ibid can be simply run out of a checkout directory:
~/code/ibid/feature-1234 $ scripts/ibid-setup
If you won’t need an administrative account, you can hit ^D
and
avoid setting one up.
Test a specific plugin:
~/code/ibid/feature-1234 $ scripts/ibid-plugin pluginname
Test with all plugins loaded:
~/code/ibid/feature-1234 $ scripts/ibid-plugin -c
Note
Not all plugin features will work in the ibid-plugin
environment.
In particular, anything relying on source-interaction or timed
callbacks (such as many of the games).
Also, all permissions are granted.
If ibid-plugin
isn’t sufficient for your debugging needs, you can
launch a normal Ibid by running:
~/code/ibid/feature-1234 $ twistd -n ibid