Interesting pages on this wiki

API and API changes

Major API changes

Each time it happens:

  • the developer is required to put a note about this in the ChangeLog?;
  • the version $(API_VERSION) of the build environment is no longer valid;
  • the work must be done is trunk or in a development branch. Not in a stable branch;

A major API change is:

  • Any change that makes any part of tinymail binary incompatible with a previous version
  • Any non-appending API change in general
  • Any change that makes reference counting act differently

Minor API changes

Each time it happens:

  • the developer is required to put a note about this in the ChangeLog?;

A minor API change is:

  • A change that appends to the existing API, yet keeps the rest of the infrastructure binary compatible with client software that only use the existing API and ABI

The Subversion repository

trunk

Trunk is for development and functions are a workplace for serious development. This means that it's unstable, might not build and shouldn't be used by packagers nor by application developers who are planning to release their software soon.

Applications built on top of tinymail better use a version from the stable branches

testing branches

Testing branches are freely created for experimenting and adding features. You can ask the maintainer (Philip) for permission and/or questions about it. But expect a positive answer.

stable branches

Stable branches have a fixed API and ABI. They receive bugfixes and might sometimes receive features additions. But never API nor ABI changes that aren't backward compatible.

Coding tips

Indentation

Just keep it clean. The maintainer doesn't really care a lot about indentation. His opinion is that the importance of strict indentation rules are overrated. Just don't make a mess of it and try to follow the original indentation of a specific file or piece of code. Please don't start running indentation fixers over your contributions.

Design

Design, however, is far more important. Most problems have already been solved once by somebody else. Most of the solutions are documented as a design pattern. Please try to reuse these existing design solutions.

But don't feel forced to exactly implement it as how the design pattern looks. Be pragmatic. But don't endanger the core idea of the design pattern itself by your pragmatism.

tinymail uses the following design patterns

  • Model View Controller for displaying lists like the headers, folders and attachments
  • Strategy for saving mime-parts (attachments)
  • Decorator for decorating a message-view with a window type
  • Iterator for all the list types
  • Proxy for the libtinymail-camel implementation (all tinymail types are like proxies for the camel types)
  • (Abstract) factory for the platform-specific implementation

tinymail utilises some important design principles

Most of these principles are indeed from the excellent O'Reilly book Head First Design Patterns. They are extremely simple. Some even simplistic. But extremely important.

  • Program to an interface, not an implementation
  • Favour composition over inheritance
  • Strive for loosely coupled designs
  • Identify the aspects of your application that vary and seperate them from what stays the same
  • Classes should be open for extension, but closed for modification

Try not to break things

Like the language bindings. If you broke it, also try to fix it or at least tell the other developers that your patch will break it.

If you rename files and types, make sure you fixup the gtk-docs in docs/devel/reference.

Unit tests

Every new API and feature needs a unit test. Yes every new one. Also your new one. And you, the developer, needs to make the unit test. Always run all unit tests before making your diff. I will run them before accepting your changes. And you will only get permission to commit things without my permission if I know I can trust you on testing using the unit tests before you commit things.

The best technique is to give me a unit test and an API before you give ma a first implementation. This clearly tells me you have designed first, created the test and them implemented your idea. This doesn't mean the API nor unit test can change anymore. But it does mean you used your brains before monkey-hacking things.

It's not wrong to use your brains. Read this page for more information on creating unit tests.

Documentation

EACH time you change public API, you MUST update the reference documentation. The maintainer will carefully guard this API reference documentation. EACH time you add API, you MUST also provide AT LEAST gtk-doc compatible reference documentation.

Read this page for more information on creating API reference documentation.

Debugging and testing

These pages contain information on debugging and testing your creations and changes: