= !TracDev/ApiChanges/0.13 =

{{{
#!div style="margin-top: .5em; padding: 0 1em; background-color: #ffd; border:1px outset #ddc; text-align: center; clear: right"

  [milestone:0.13] corresponds to the development version of Trac (a.k.a. [source:trunk]) \\
  These notes reflect the current status.
}}}

[[PageOutline(2-4,Summary,inline)]]


== Prerequisites ==

Python 2.4 support has been dropped.
Python versions 2.5, 2.6 and 2.7 are supported.

=== Modified Dependencies ===

==== jQuery (bundled)

The bundled version of [http://jquery.com jQuery] is now 1.5 instead of 1.4.4 in Trac 0.12-stable.
{{{#!comment
Among other things, this means that (//list most visible incompatible changes...//).
}}}
See jQuery 1.5 [http://blog.jquery.com/2011/01/31/jquery-15-released/ release notes] and [http://api.jquery.com/category/version/1.5/ API documentation].

//(TODO: upgrade to latest)// 

==== Babel (optional)

The internationalization support (i18) for Trac is depending on [http://babel.edgewall.org/ Babel].

Q: Should we now make Babel a mandatory dependency, as we have a good stable release?

This would allow us to use the Babel API in more places (e.g. #4636, #2182).

A: (cboos) I think having it optional doesn't prevent us to make further use of it when it's available. We just need to use fallback code when it's not (see #2182). 

==== Clearsilver (dropped)

Support for ClearSilver templates has been dropped. In case your plugin was still using `.cs` templates, PortingFromClearSilverToGenshi is now mandatory.

==== Genshi (mandatory)

 * '''Genshi 0.7''' changed to accepting `unicode` instances by default, rather than UTF-8 encoded regular `str` instances. Trac has been updated to override the default back to UTF-8 but plugins that access Genshi directly might raise an error: `UnicodeError: source returned bytes, but no encoding specified`.
 * '''Genshi 0.6.x''' is still supported and will likely be a safer alternative. See #10126 for details.


{{{#!comment
=== New Dependencies ===

None!
}}}


== Detailed List of Developer Visible Changes

[[TicketQuery(milestone=0.13|0.12.1|0.12.2,status=closed,apichanges!=,col=apichanges,group=component,format=table)]] 

== Other Modifications made to the 0.12 API ==
{{{#!comment
=== Modified Interfaces ===
==== `I...`            ^[source:trunk/trac/.../api.py@rev:highlighted-linenum#Lnum (0.13)] [source:branches/0.12-stable/trac/.../api.py@rev:rev:highlighted-linenum#Lnum (0.12)]^ ==== #I...r

...
}}}

=== Database API Changes ===

==== `Environment.get_db_cnx` is obsolete #get_db_cnx

Following the deprecation [../0.12#get_db_cnx deprecation] made in 0.12, using `Environment.get_db_cnx` for obtaining a database connection is now considered ''obsolete'' and its use is heavily discouraged, as that method will be removed in Trac 0.14.

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:
   {{{#!python
   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:
   {{{#!python
   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.db_query()` and `Environment.db_transaction()` ^[source:trunk/trac/env.py@#Lnum (0.13)]^ ==== #with_transaction

The `@with_transaction(env)` / `@env.with_transaction()` decorators introduced in 0.12 remain available, but they're now deprecated as well, as the `with` syntax is the one to be used. Those decorators will likely be removed in Trac 0.14 as well.

See #8751 for details and related notes about [#get_db_cnx get_db_cnx] deprecation above.


== New in the 0.13 API ==

Be sure to have a look at the new ApiDocs ([http://www.edgewall.org/docs/trac-trunk/html/ for latest trunk]).
\\ //work in progress - coverage is not complete yet//

{{{#!comment
=== New Classes ===
==== `trac.x.y.ClassName` ^[source:trunk/trac/x/y.py@#Lnum (0.13)]^ ==== #ClassName

...

=== New Interfaces ===
==== `trac.x.y.IClassName` ^[source:trunk/trac/x/y.py@#Lnum (0.13)]^ ==== #IClassName


=== Other news ===

}}}