1 | | {{{#!div style="float: right; margin: 0 1em" |
2 | | ← [../1.1.3] | [../1.1.5] → |
3 | | }}} |
4 | | = Documenting API changes since 1.1.3 |
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.4], 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 | | || !ConfigObj || Optional || Unspecified. Let's consider enforcing a minimum version, such as >= 5.0. !ConfigObj 5.0 released on [pypi:configobj/5.0.0 2014-02-15] || |
80 | | || !DocUtils || Optional || >= 0.3.9 || |
81 | | || Textile || Optional || >= 2.0 || |
82 | | || 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] || |
83 | | ... please add any dependencies I've overlooked. |
84 | | |
85 | | === Deprecated Modules Removed |
86 | | |
87 | | TODO Remove support for `mod_python` (see TracModPython) ... or maybe not. It seems the project is alive (comment:34:ticket:11605). |
88 | | |
89 | | DONE: Removed Enscript, SilverCity and PHP renderers. |
90 | | |
91 | | === New Dependencies |
92 | | |
93 | | None! |
94 | | |
95 | | |
96 | | == Detailed List of Developer Visible Changes #list |
97 | | |
98 | | [[TicketQuery(milestone=1.1.4,status=closed,apichanges!=,col=summary,rows=apichanges,group=component,format=table)]] |
99 | | |
100 | | == Other Modifications made to the 1.0 API |
101 | | |
102 | | 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 |
103 | | |
104 | | === Modified Interfaces |
105 | | ==== `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 |
106 | | |
107 | | 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. |
108 | | |
109 | | ==== `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 |
110 | | |
111 | | [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. |
112 | | |
113 | | === New Interfaces === |
114 | | ==== `trac.notification.api.INotificationDistributor` ^[source:trunk/trac/notification/api.py@13454#L29 (1.1.3)]^ ==== #INotificationDistributor |
115 | | |
116 | | 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). |
117 | | |
118 | | ==== `trac.notification.api.INotificationFormatter` ^[source:trunk/trac/notification/api.py@13454#L46 (1.1.3)]^ ==== #INotificationFormatter |
119 | | |
120 | | 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). |
121 | | |
122 | | ==== `trac.notification.api.INotificationSubscriber` ^[source:trunk/trac/notification/api.py@13469#L70 (1.1.3)]^ #INotificationSubscriber |
123 | | |
124 | | 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). |
125 | | |
126 | | ==== `trac.notification.api.IEmailAddressResolver` ^[source:trunk/trac/notification/api.py@13454#L67 (1.1.3)]^ #IEmailAddressResolver |
127 | | |
128 | | 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). |
129 | | |
130 | | ==== `trac.notification.api.IEmailDecorator` ^[source:trunk/trac/notification/api.py@13454#L79 (1.1.3)]^ ==== #IEmailDecorator |
131 | | |
132 | | 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. |
133 | | |
134 | | === Notification API Changes |
135 | | |
136 | | 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]) |
137 | | |
138 | | === Database API Changes |
139 | | |
140 | | 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). |
141 | | |
142 | | ==== `Environment.get_db_cnx` has been removed #get_db_cnx |
143 | | |
144 | | Following the [../0.12#get_db_cnx deprecation] made in 0.12, the method `Environment.get_db_cnx` has been removed. |
145 | | |
146 | | One should now only use the //context managers// for retrieving a database Connection |
147 | | in read or write mode. |
148 | | - a **read-only** Connection can be used to form queries: |
149 | | {{{#!python |
150 | | with env.db_query as db: |
151 | | ... |
152 | | }}} |
153 | | a `db` instance obtained the above way should only be used for executing //SELECT// |
154 | | queries |
155 | | - a **writable** Connection can be used to modify the database content in a transaction: |
156 | | {{{#!python |
157 | | with env.db_transaction as db: |
158 | | ... |
159 | | }}} |
160 | | a `db` instance obtained the above way can be used to execute //INSERT/UPDATE/DELETE// |
161 | | queries; they will be committed when the last such automatic transaction |
162 | | in the control flow completes successfully. See DatabaseApi for the full details. |
163 | | |
164 | | `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. |
165 | | |
166 | | |
167 | | ==== `db` parameters removed from function and method signatures |
168 | | |
169 | | 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]. |
170 | | |
171 | | 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. |
172 | | |
173 | | |
174 | | ==== `ConnectionBase` class |
175 | | |
176 | | The `ConnectionBase` class defines an abstract interface that database backends must adhere to when implementing a `Connection` class. |
177 | | |
178 | | |
179 | | === Template and CSS changes |
180 | | |
181 | | `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. |
182 | | |
183 | | 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. |
184 | | |
185 | | //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.// |
186 | | |
187 | | |
188 | | === Uncategorized Changes |
189 | | |
190 | | DONE: Remove deprecated compatibility code for InterTrac links: [browser:/trunk/trac/wiki/formatter.py@13050:703-712#L696], and remove documentation: |
191 | | * InterWiki page |
192 | | * [browser:/trunk/trac/wiki/intertrac.py@13050:50-60#L30] |
193 | | |
194 | | DONE: Removed the deprecated `authname` parameter from `Environment.get_repository()`. |
195 | | |
196 | | TODO: Log warnings for deprecated functions and methods (comment:26:ticket:11605) |
197 | | |
198 | | |
199 | | == New in the 1.1.4 API |
200 | | |
201 | | Be sure to have a look at the new ApiDocs ([http://www.edgewall.org/docs/trac-trunk/html/ for latest trunk]). |
202 | | |
203 | | TODO: Remove //Since// info from docstrings for Trac < 0.12. |
204 | | |
205 | | //This is a work in progress - coverage is still not yet complete.// |
206 | | |
207 | | |
208 | | |
209 | | {{{#!comment |
210 | | === New Classes |
211 | | ==== `trac.x.y.ClassName` ^[source:trunk/trac/x/y.py@#Lnum (1.0)]^ #ClassName |
212 | | |
213 | | ... |
214 | | |
215 | | === Other news |
216 | | |
217 | | }}} |
| 1 | See [../1.1] |