Edgewall Software

Version 2 (modified by Ryan J Ollos, 9 years ago) ( diff )

Updated ticket query for milestone.

← 1.1.4 | 1.1.6 →

Documenting API changes since 1.1.4

The next stable version of Trac will be named 1.2 and will contain the cumulative changes made in the successive 1.1.x releases.

These notes reflect the current status for 1.1.5, in trunk​.

Proposed changes are prefixed with an OPEN mark and the paragraph is written in italics.

Summary

  1. Prerequisites
    1. Modified Dependencies
      1. jQuery and jQuery UI (bundled)
      2. Babel (optional)
      3. Genshi (mandatory)
      4. Databases
      5. Other
    2. Deprecated Modules Removed
    3. New Dependencies
  2. Detailed List of Developer Visible Changes
  3. Other Modifications made to the 1.0 API
    1. Modified Interfaces
      1. IWikiChangeListener (1.1.3)​ (1.0)​
      2. IPreferencePanelProvider (1.1.3)​ (1.0)​
    2. New Interfaces
      1. trac.notification.api.INotificationDistributor (1.1.3)​
      2. trac.notification.api.INotificationFormatter (1.1.3)​
      3. trac.notification.api.INotificationSubscriber (1.1.3)​
      4. trac.notification.api.IEmailAddressResolver (1.1.3)​
      5. trac.notification.api.IEmailDecorator (1.1.3)​
    3. Notification API Changes
    4. Database API Changes
      1. Environment.get_db_cnx has been removed
      2. db parameters removed from function and method signatures
      3. ConnectionBase class
    5. Template and CSS changes
    6. Uncategorized Changes
  4. New in the 1.1.5 API

Prerequisites

Only Python versions 2.6 and 2.7 are supported.

The following language features introduced in Python 2.6 can now be used and the related clean-ups can be done:

  • use string ​format(), print()
  • except Cls as val
  • class decorators to avoid the implements hack?
  • @prop.setter / @prop.deleter
  • namedtuples!
  • there's no longer need of from __future__ import with_statement
  • next(iterator, [default]) to clean-up some unit tests
  • timeout in smtplib

TODO List supported browsers. Consider using ​jQuery's list.

Modified Dependencies

See ​gmessage:trac-dev:nkMUY_8ILF0/rg1rsArDIewJ for a discussion about what dependencies we'll support in Trac 1.2.

jQuery and jQuery UI (bundled)

The bundled version of ​jQuery will be 1.9 / 2.0 instead of 1.8.3 in Trac 1.1.1.

See jQuery release notes for the corresponding major updates:

OPEN The bundled version of the full minified ​jQuery UI package will be at least ​1.11.2. See #11019.

Babel (optional)

The internationalization support (i18) for Trac is depending on ​Babel, version 1.0. (#10882) TODO

Babel ≥ 0.9.5 is still supported.

Genshi (mandatory)

OPEN Genshi 0.7

Genshi 0.6.x is still supported.

Databases

Database
SQLite ≥ 3.0
PostgreSQL ≥ 8.0
MySQL / MariaDB ≥ 5.0
Database Bindings
pysqlite ≥ 2.4.1 (version provided by Python 2.6), avoid 2.5.2 - 2.5.4
psycopg2 ≥ 2.0
MySQLdb ≥ 1.2.2

Other

Package Req or Opt? Version supported
SetupTools Required ≥ 0.6, 5.4 - 5.6 are not recommended.
Git Optional ≥ 1.5.6
Subversion Optional ≥ 1.6
ConfigObj Optional Unspecified. Let's consider enforcing a minimum version, such as ≥ 5.0. ConfigObj 5.0 released on ​2014-02-15
DocUtils Optional ≥ 0.3.9
Textile Optional ≥ 2.0
Pygments Optional ≥ 0.6. Let's consider bumping the requirement to at least 1.0, released in ​2008

… please add any dependencies I've overlooked.

Deprecated Modules Removed

TODO Remove support for mod_python (see TracModPython) … or maybe not. It seems the project is alive (comment:34:ticket:11605).

DONE Removed Enscript, SilverCity and PHP renderers.

New Dependencies

None!

Detailed List of Developer Visible Changes

Component: contrib (1 match)

Ticket Summary
#10975 Enhancement for the contrib/htpasswd.py script
API Changes
  • trac.util.compat provides an import of the crypt.crypt method that will fallback to fcrypt module when crypt module is not available. None is returned if fcrypt is not available.
  • trac.util provides the salt function for use with cryptographic hash functions.

Component: database backend (1 match)

Ticket Summary
#11978 Add drop_schema method to ConnectionBase class
API Changes
  • Added destroy_db method to the DatabaseManager class, the IDatabaseConnector interface and implementations of the IDatabaseConnector interface.
  • The keyword parameters of EnvironmentStub's destroy_db method are deprecated.

Component: general (4 matches)

Ticket Summary
#6551 IntOption and BoolOption values saved even when not differing from default
API Changes
  • Configuration.get always returns a string, as documented.
  • Configuration values are normalized before writing to file.
  • Moved get_configinfo (added in 1.1.2) from Environment class to a function of the config module.
#8172 Plugin db upgrade infrastructure
API Changes

Added needs_upgrade() and upgrade() methods to the DatabaseManager class.

#11982 Remove dependency on ConfigObj
API Changes

Added OrderedDict to trac.util.compat module for Python 2.6 compatibility.

#12008 Deleting unevaluated `@lazy` attribute raises KeyError
API Changes

Changed trac.util.lazy: for x decorated @lazy and not yet evaluated, del x does not raise KeyError anymore.

Component: notification (1 match)

Ticket Summary
#11875 Notification subscriber config section
API Changes

Added trac.notification.api.parse_subscriber_config(), NotificationSystem.notification_subscriber_section, NotificationSystem.subscriber_defaults and NotificationSystem.default_subscriptions().

Component: rendering (1 match)

Ticket Summary
#12010 Pygments preferences template should be located in mimeview package
API Changes

prefs_pygments.html moved from trac/prefs/templates to trac/mimeview/templates.

Component: timeline (1 match)

Ticket Summary
#12048 [PATCH] Add scope to CSS rules in timeline.css
API Changes

Timeline CSS rules are scoped to the .timeline class.

Component: version control (1 match)

Ticket Summary
#11995 Versioncontrol API for changeset bookmarks
API Changes

Add new Changeset.get_bookmarks() API.

Other Modifications made to the 1.0 API

Take the will be removed in version 1.1.1 comments in the code seriously. The earlier the planned API changes in 1.1.x, the better (gives more time to plugin authors to adapt). TODO

Modified Interfaces

IWikiChangeListener (1.1.3)​ (1.0)​

Wiki page version comments can now be edited, so wiki_page_comment_modified(page, old_comment) has been added to allow plugins to be notified of this.

IPreferencePanelProvider (1.1.3)​ (1.0)​

IPreferencePanelProvider implementations can now provide child panels that appear as sections appended to other panels (proposal). This allows plugins to extend existing preference panels.

New Interfaces

trac.notification.api.INotificationDistributor (1.1.3)​

A new INotificationDistributor interface was added (proposal). It allows plugins to distribute notifications on different channels (e.g. over XMPP).

trac.notification.api.INotificationFormatter (1.1.3)​

A new INotificationFormatter interface was added (proposal). It allows plugins to format notifications (e.g. to HTML).

trac.notification.api.INotificationSubscriber (1.1.3)​

A new INotificationSubscriber interface was added (proposal). It allows plugins to provide more subscription preferences (e.g. to send or suppress notifications under special conditions).

trac.notification.api.IEmailAddressResolver (1.1.3)​

A new IEmailAddressResolver interface was added (proposal). It allows plugins to retrieve email addresses from users (e.g. from LDAP).

trac.notification.api.IEmailDecorator (1.1.3)​

A new IEmailDecorator interface was added (proposal). It allows plugins to add or tweak email headers.

Notification API Changes

To take advantage of the new notification related interfaces, code that sends notifications must use the new Notification API instead of the NotifyEmail class hierarchy. (See proposal)

Database API Changes

Methods have been added to DatabaseManager class for settings and retrieving the database version for Trac and plugins: set_database_version and get_database_version (#11859).

Environment.get_db_cnx has been removed

Following the deprecation made in 0.12, the method Environment.get_db_cnx has been removed.

One should now only use the context managers for retrieving a database Connection in read or write mode.

  • a read-only Connection can be used to form queries: 
    with env.db_query as db:
    ...
    a db instance obtained the above way should only be used for executing SELECT queries
  • a writable Connection can be used to modify the database content in a transaction: 
    with env.db_transaction as db:
    ...
    a db instance obtained the above way can be used to execute INSERT/UPDATE/DELETE queries; they will be committed when the last such automatic transaction in the control flow completes successfully. See DatabaseApi for the full details.

Environment.get_read_db and the decorators @with_transaction(env) and env.with_transaction() have been deprecated since Trac 1.0 and will be removed in Trac 1.3.1.

db parameters removed from function and method signatures

With the introduction of @with_transaction(env) decorators in 0.12 and continuing with the introduction of the database connection context managers in 1.0, the db parameters passed as function and method arguments became deprecated.

The db parameters have been removed from nearly all function and method signatures. The db arguments are still present on methods of IEnvironmentParticipant implementations, but are deprecated and should no longer be used. They will be removed in 1.3.1.

ConnectionBase class

The ConnectionBase class defines an abstract interface that database backends must adhere to when implementing a Connection class.

Template and CSS changes

tt tags are not support in HTML5 and have been replaced with code tags in Trac (#11094). The styling of tt and code tags is the same in Trac , but code tags should be used since the styling for tt tags will be removed in a future version of Trac.

The about.css stylesheet has been removed and the rules contained in that stylesheet have been moved to trac.css. The table of environment information on the Error and About pages have been extracted to a new template environment_info.html and the markup and associated rules in the stylesheet have been significantly changed.

Many more changes to be added, depending on how details we want to get. TracUpgrade#CustomizedTemplates claims that changes to ids and CSS classes will be documented in ApiChanges.

Uncategorized Changes

DONE Remove deprecated compatibility code for InterTrac links: trunk/trac/wiki/formatter.py@13050:703-712#L696​, and remove documentation:

DONE Removed the deprecated authname parameter from Environment.get_repository().

TODO Log warnings for deprecated functions and methods (comment:26:ticket:11605)

New in the 1.1.5 API

Be sure to have a look at the new ApiDocs (​for latest trunk).

TODO Remove Since info from docstrings for Trac < 0.12.

This is a work in progress - coverage is still not yet complete.

Note: See TracWiki for help on using the wiki.