Contributing — Ibid v0.1.1 documentation

### Navigation

- index
- modules |
- next |
- previous |
- Ibid v0.1.1 documentation »

# 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:

1. If you don’t have one, create a Launchpad account and configure Bazaar to use it.

2. If there isn’t a bug in the tracker for this change, file one. It motivates the change.

3. Mark the bug as In Progress, assigned to you.

4. 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.

5. Fix your bug in this branch, following the Style Guidelines. See also Running a Development Ibid.

6. Link the commit that fixes the bug to the launchpad bug:

       user@box $ bzr commit --fixes lp:1234

7. Test that the fix works as expected and doesn’t introduce any new bugs. `pyflakes` can find syntax errors you missed.

8. Run the test-cases:

       user@box $ trial ibid

9. Push the branch to Launchpad:

       user@box $ bzr push lp:~yourname/ibid/description-1234

10. Find the branch on Launchpad and propose it for merging into the Ibid trunk.

11. 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.

## Bazaar for Ibid Developers

You’ll want a non-ancient version (>=1.6) 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 --1.6 .

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:

- Launchpad code hosting documentation
- Using Bazaar with Launchpad
- Bazaar User Guide
- Bazaar Reference

## 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

### Navigation

- index
- modules |
- next |
- previous |
- Ibid v0.1.1 documentation »