= Evolution of the Trac API

== Guidelines for API changes

**Always try to maintain API compatibility.**

If an interface ''must'' be changed:
   * try to maintain the old interface for at
     least one minor version change (e.g. [milestone:0.10] -> [milestone:0.11]) 
   * log deprecation warnings if the old method is used
   * document the API change:
     - in '''!TracDev/ApiChanges/<version>'''
       or in the //API changes// field of the corresponding ticket if any.
     - in the docstring, make use of the [http://sphinx.pocoo.org/markup/para.html?highlight=versionadded#directive-versionchanged .. versionmodified::] and `.. deprecated::` directives.

If the old interface can't be maintained, document it as such in the appropriate '''!TracDev/ApiChanges/<version>''' page.


== Detailed changes per version ==
** !TracDev/ApiChanges/ [[TitleIndex(TracDev/ApiChanges/,hideprefix,format=compact)]]**

See also the ApiDocs themselves.


== Development Milestones ==
=== Milestone [milestone:1.0] ===
 * [10189]: db API refactoring, using the `with` keyword (DatabaseApi#Trac0.13API)

=== Milestone [milestone:0.12] ===
 * [9825]: 0.12rc1 - javascript translations and setup.py changes  
   (`get_l10n_cmdclass` and `get_l10n_js_cmdclass`)
 * [9595]: 0.12b1
 * [9260]: templates/macros.html deprecated
 * [9224]: zero-padding of revision numbers in the repository cache ('''upgrade needed''')
 * [9210]: timestamps stored as bigints (microsecond resolution) in the db ('''upgrade needed''')
 * [9175]: MultiRepos merge, ('''repository resync needed''')
 * ... (well, tons of changes)
 * r7705: i18n support for plugins - you'll need 
   Genshi's [Genshi:source:branches/experimental/advanced-i18n@967 advanced-i18n]
   for getting translated templates.
 * !r6986: Internationalization support


=== Milestone [milestone:0.11] ===
 * r6805: functional tests available in trunk (see [source:/trunk/TESTING-README TESTING-README])
 * r6572: enabled the "noConflict" mode for jQuery, so that other Javascript libraries using '$' in a special way can be used. As a result, plugins using jQuery should be updated (follow the advice in http://trac.edgewall.org/changeset/6572#file11). Whether this change will stay or be reverted is under discussion. ''update: well, the change has actually been reverted without much discussion in r6715.''
 * ''r6352'' removed the `req.warning("...")` call. Replace it with `add_warning(req, "...")`.
 * ''r6139 integrated the API changes developed in the context-refactoring branch. The early 0.11dev plugins most probably need to be adapted. See the ["TracDev/ApiChanges/0.11"] page.''
 * r5514: [wiki:TracDev/SecurityBranch Flexible permission system]
 * r5378: Flexible/extensible [TracWorkflow ticket workflow]
 * r4819: [SetupTools Setuptools] integration
 * r4095: WebAdmin integration
 * r4561: versioncontrol "blame" support
 * r3947: [http://jquery.com/ jQuery] integration
 * r3935: Timezone support and internal use of `datetime`
 * r3832: [http://genshi.edgewall.org/ Genshi] integration ([query:status=!closed&keywords=~genshi open tickets])