1 | | {{{#!div style="float: right; margin: 0 1em" |
2 | | ← [../1.1.4] | [../1.1.6] → |
3 | | }}} |
4 | | = Documenting API changes since 1.1.4 |
5 | | |
6 | | {{{#!box info |
7 | | 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. |
8 | | |
9 | | These notes reflect the current status for [milestone:1.1.5], in [source:trunk]. |
10 | | |
11 | | Proposed changes are prefixed with an OPEN mark and the //paragraph is written in italics.// |
12 | | }}} |
13 | | |
14 | | [[PageOutline(2-4,Summary,inline)]] |
15 | | |
16 | | |
17 | | == Prerequisites |
18 | | |
19 | | **Only Python versions 2.6 and 2.7 are supported.** |
20 | | |
21 | | The following language features introduced in Python 2.6 can now be used and the related clean-ups can be done: |
22 | | - use string [http://docs.python.org/library/string.html#string-formatting format()], `print()` |
23 | | - `except Cls as val` |
24 | | - class decorators to avoid the `implements` hack? |
25 | | - `@prop.setter` / `@prop.deleter` |
26 | | - `namedtuple`s! |
27 | | - there's no longer need of `from __future__ import with_statement` |
28 | | - `next(iterator, [default])` to clean-up some unit tests |
29 | | - timeout in smtplib |
30 | | |
31 | | TODO: List supported browsers. Consider using [http://jquery.com/browser-support/ jQuery's list]. |
32 | | |
33 | | === Modified Dependencies |
34 | | |
35 | | See gmessage:trac-dev:nkMUY_8ILF0/rg1rsArDIewJ for a discussion about what dependencies we'll support in Trac 1.2. |
36 | | |
37 | | ==== jQuery and jQuery UI (bundled) |
38 | | |
39 | | The bundled version of [http://jquery.com jQuery] will be **1.9 / 2.0** instead of 1.8.3 in Trac 1.1.1. |
40 | | |
41 | | See jQuery release notes for the corresponding major updates: |
42 | | - http://blog.jquery.com/2013/01/15/jquery-1-9-final-jquery-2-0-beta-migrate-final-released/ |
43 | | |
44 | | OPEN // |
45 | | The bundled version of the full minified [http://jqueryui.com jQuery UI] package will be at least [http://jqueryui.com/docs/Changelog/1.11.2 1.11.2]. See #11019. |
46 | | // |
47 | | |
48 | | ==== Babel (optional) |
49 | | |
50 | | The internationalization support (i18) for Trac is depending on [http://babel.edgewall.org/ Babel], version 1.0. (#10882) TODO |
51 | | |
52 | | //Babel >= 0.9.5 is still supported.// |
53 | | |
54 | | ==== Genshi (mandatory) |
55 | | |
56 | | OPEN |
57 | | // '''Genshi 0.7''' // |
58 | | |
59 | | //Genshi 0.6.x is still supported.// |
60 | | |
61 | | |
62 | | ==== Databases |
63 | | |
64 | | |||| **Database** || |
65 | | || SQLite || >= 3.0 || |
66 | | || PostgreSQL || >= 8.0 || |
67 | | || MySQL / MariaDB || >= 5.0 || |
68 | | |||| **Database Bindings** || |
69 | | || pysqlite || >= 2.4.1 (version provided by Python 2.6), avoid 2.5.2 - 2.5.4 || |
70 | | || psycopg2 || >= 2.0 || |
71 | | || MySQLdb || >= 1.2.2 || |
72 | | |
73 | | ==== Other |
74 | | |
75 | | || Package || Req or Opt? || Version supported || |
76 | | || SetupTools || Required || >= 0.6, 5.4 - 5.6 are not recommended. || |
77 | | || Git || Optional || >= 1.5.6 || |
78 | | || Subversion || Optional || >= 1.6 || |
79 | | || !DocUtils || Optional || >= 0.3.9 || |
80 | | || Textile || Optional || >= 2.0 || |
81 | | || Pygments || Optional || >= 0.6. Let's consider bumping the requirement to at least 1.0, released in [https://pypi.python.org/pypi/Pygments/1.0 2008] || |
82 | | ... please add any dependencies I've overlooked. |
83 | | |
84 | | `ConfigObj` is no longer a required dependency for the `AuthzPolicy` permission policy (`tracopt.perm.authz_policy`). |
85 | | |
86 | | === Deprecated Modules Removed |
87 | | |
88 | | TODO Remove support for `mod_python` (see TracModPython) ... or maybe not. It seems the project is alive (comment:34:ticket:11605). |
89 | | |
90 | | DONE: Removed Enscript, SilverCity and PHP renderers. |
91 | | |
92 | | === New Dependencies |
93 | | |
94 | | None! |
95 | | |
96 | | |
97 | | == Detailed List of Developer Visible Changes #list |
98 | | |
99 | | [[TicketQuery(milestone=1.1.5,status=closed,apichanges!=,col=summary,rows=apichanges,group=component,format=table)]] |
100 | | |
101 | | == Other Modifications made to the 1.0 API |
102 | | |
103 | | 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 |
104 | | |
105 | | === Modified Interfaces |
106 | | ==== `IWikiChangeListener` ^[source:trunk/trac/wiki/api.py@13198:53#L32 (1.1.3)] [source:branches/1.0-stable/trac/wiki/api.py@11490#L33 (1.0)]^ #IWikiChangeListener |
107 | | |
108 | | 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. |
109 | | |
110 | | ==== `IPreferencePanelProvider` ^[source:trunk/trac/prefs/api.py@13510:23#L17 (1.1.3)] [source:branches/1.0-stable/trac/prefs/api.py@11490#L17 (1.0)]^ #IPreferencePanelProvider |
111 | | |
112 | | [wiki:TracDev/PluginDevelopment/ExtensionPoints/trac.prefs.api.IPreferencePanelProvider IPreferencePanelProvider] implementations can now provide child panels that appear as sections appended to other panels ([wiki:TracDev/Proposals/AdvancedNotification#Modularpreferencepages proposal]). This allows plugins to extend existing preference panels. |
113 | | |
114 | | === New Interfaces === |
115 | | ==== `trac.notification.api.INotificationDistributor` ^[source:trunk/trac/notification/api.py@13454#L29 (1.1.3)]^ ==== #INotificationDistributor |
116 | | |
117 | | A new [wiki:TracDev/PluginDevelopment/ExtensionPoints/trac.notification.api.INotificationDistributor INotificationDistributor] interface was added ([wiki:TracDev/Proposals/AdvancedNotification#ExtensionAPIformaildistribution proposal]). It allows plugins to distribute notifications on different channels (e.g. over XMPP). |
118 | | |
119 | | ==== `trac.notification.api.INotificationFormatter` ^[source:trunk/trac/notification/api.py@13454#L46 (1.1.3)]^ ==== #INotificationFormatter |
120 | | |
121 | | A new [wiki:TracDev/PluginDevelopment/ExtensionPoints/trac.notification.api.INotificationFormatter INotificationFormatter] interface was added ([wiki:TracDev/Proposals/AdvancedNotification#ExtensionAPIformaildistribution proposal]). It allows plugins to format notifications (e.g. to HTML). |
122 | | |
123 | | ==== `trac.notification.api.INotificationSubscriber` ^[source:trunk/trac/notification/api.py@13469#L70 (1.1.3)]^ #INotificationSubscriber |
124 | | |
125 | | A new [wiki:TracDev/PluginDevelopment/ExtensionPoints/trac.notification.api.INotificationSubscriber INotificationSubscriber] interface was added ([wiki:TracDev/Proposals/AdvancedNotification#ExtensionAPIforsubscriptions proposal]). It allows plugins to provide more subscription preferences (e.g. to send or suppress notifications under special conditions). |
126 | | |
127 | | ==== `trac.notification.api.IEmailAddressResolver` ^[source:trunk/trac/notification/api.py@13454#L67 (1.1.3)]^ #IEmailAddressResolver |
128 | | |
129 | | A new [wiki:TracDev/PluginDevelopment/ExtensionPoints/trac.notification.api.IEmailAddressResolver IEmailAddressResolver] interface was added ([wiki:TracDev/Proposals/AdvancedNotification#ExtensionAPIformaildistribution proposal]). It allows plugins to retrieve email addresses from users (e.g. from LDAP). |
130 | | |
131 | | ==== `trac.notification.api.IEmailDecorator` ^[source:trunk/trac/notification/api.py@13454#L79 (1.1.3)]^ ==== #IEmailDecorator |
132 | | |
133 | | A new [wiki:TracDev/PluginDevelopment/ExtensionPoints/trac.notification.api.IEmailDecorator IEmailDecorator] interface was added ([wiki:TracDev/Proposals/AdvancedNotification#ExtensionAPIformaildistribution proposal]). It allows plugins to add or tweak email headers. |
134 | | |
135 | | === Notification API Changes |
136 | | |
137 | | To take advantage of the new notification related interfaces, code that sends notifications must use the new [wiki:TracDev/NotificationApi Notification API] instead of the `NotifyEmail` class hierarchy. (See [wiki:TracDev/Proposals/AdvancedNotification#ExtensionAPIformaildistribution proposal]) |
138 | | |
139 | | === Database API Changes |
140 | | |
141 | | 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). |
142 | | |
143 | | ==== `Environment.get_db_cnx` has been removed #get_db_cnx |
144 | | |
145 | | Following the [../0.12#get_db_cnx deprecation] made in 0.12, the method `Environment.get_db_cnx` has been removed. |
146 | | |
147 | | One should now only use the //context managers// for retrieving a database Connection |
148 | | in read or write mode. |
149 | | - a **read-only** Connection can be used to form queries: |
150 | | {{{#!python |
151 | | with env.db_query as db: |
152 | | ... |
153 | | }}} |
154 | | a `db` instance obtained the above way should only be used for executing //SELECT// |
155 | | queries |
156 | | - a **writable** Connection can be used to modify the database content in a transaction: |
157 | | {{{#!python |
158 | | with env.db_transaction as db: |
159 | | ... |
160 | | }}} |
161 | | a `db` instance obtained the above way can be used to execute //INSERT/UPDATE/DELETE// |
162 | | queries; they will be committed when the last such automatic transaction |
163 | | in the control flow completes successfully. See DatabaseApi for the full details. |
164 | | |
165 | | `Environment.get_read_db` and the decorators `@with_transaction(env)` and `env.with_transaction()` have been [../1.0#with_transaction deprecated] since Trac 1.0 and will be removed in Trac 1.3.1. |
166 | | |
167 | | |
168 | | ==== `db` parameters removed from function and method signatures |
169 | | |
170 | | 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 [../0.12#Othernews deprecated]. |
171 | | |
172 | | 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. |
173 | | |
174 | | |
175 | | ==== `ConnectionBase` class |
176 | | |
177 | | The `ConnectionBase` class defines an abstract interface that database backends must adhere to when implementing a `Connection` class. |
178 | | |
179 | | |
180 | | === Template and CSS changes |
181 | | |
182 | | `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. |
183 | | |
184 | | 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. |
185 | | |
186 | | //Many more changes to be added, depending on how details we want to get. TracUpgrade#CustomizedTemplates claims that changes to `id`s and CSS `class`es will be documented in ApiChanges.// |
187 | | |
188 | | |
189 | | === Uncategorized Changes |
190 | | |
191 | | DONE: Remove deprecated compatibility code for InterTrac links: [browser:/trunk/trac/wiki/formatter.py@13050:703-712#L696], and remove documentation: |
192 | | * InterWiki page |
193 | | * [browser:/trunk/trac/wiki/intertrac.py@13050:50-60#L30] |
194 | | |
195 | | DONE: Removed the deprecated `authname` parameter from `Environment.get_repository()`. |
196 | | |
197 | | TODO: Log warnings for deprecated functions and methods (comment:26:ticket:11605) |
198 | | |
199 | | |
200 | | == New in the 1.1.5 API |
201 | | |
202 | | Be sure to have a look at the new ApiDocs ([http://www.edgewall.org/docs/trac-trunk/html/ for latest trunk]). |
203 | | |
204 | | TODO: Remove //Since// info from docstrings for Trac < 0.12. |
205 | | |
206 | | //This is a work in progress - coverage is still not yet complete.// |
207 | | |
208 | | |
209 | | |
210 | | {{{#!comment |
211 | | === New Classes |
212 | | ==== `trac.x.y.ClassName` ^[source:trunk/trac/x/y.py@#Lnum (1.0)]^ #ClassName |
213 | | |
214 | | ... |
215 | | |
216 | | === Other news |
217 | | |
218 | | }}} |
| 1 | See [../1.1] |