3 Last modified at [$Date: 2002/10/19 17:41:51 $]
8 The Apache HTTP Server project must balance two competing and disjoint
9 objectives: maintain stable code for third party authors, distributors and
10 most importantly users so that bug and security fixes can be quickly adopted
11 without significant hardship due to user-visible changes; and continue the
12 development process that requires ongoing redesign to correct earlier
13 oversights and to add additional features.
15 The Apache HTTP Server, through version 2.0, used the Module Magic Number (MMN)
16 to reflect API changes. This had the shortcoming of often leaving users
17 hunting to replace binary third party modules that were now incompatible.
18 This also left module authors searching through the API change histories to
19 determine the exact cause for the MMN change and whether their module was
22 With the simultaneous release of Apache 2.2-stable and Apache 2.3-development,
23 the Apache HTTP Server project is moving towards a more predictable stable
24 release cycle, while allowing forward progress to occur without concern
25 for breaking the stable branch. This document explains the rationale between
26 the two versions and their behavior.
29 STABLE RELEASES, 2.{even}.{revision}
30 ------------------------------------
32 All even numbered releases will be considered stable revisions.
34 Stable revisions will retain forward compatiblity to the maximum
35 possible extent. Features may be added during minor revisions, and
36 features may be deprecated by making appropriate notations in the
37 documentation, but no features may be removed.
39 In essence, that implies that you can upgrade from one minor revision
40 to the next with a minimum of trouble. In particular, this means:
42 * The Module API will retain forward compatibility.
43 It will not be necessary to update modules to work with new
44 revisions of the stable tree.
46 * The run-time configuration will be forward compatible.
47 No configuration changes will be necessary to work with new
48 revisions of the stable tree.
50 * Compile-time configuration will be forward compatible.
51 The configure command line options that work in one release
52 of the stable tree will also work in the next release.
54 As always, it will be necessary to test any new release to assure
55 that it works correctly with a particular configuration and a
56 particular set of modules, but every effort will be made to assure
57 that upgrades are as smooth as possible.
59 In addition, the following development restrictions will aid in
60 keeping the stable tree as safe as possible:
62 * No 'Experimental' modules; while it may be possible (based on API changes
63 required to support a given module) to load a 2.3-development module into
64 a 2.2-stable build of Apache, there are no guarantees. Experimental
65 modules will be introduced to the 2.3-development versions and either
66 added to 2.2-stable once they are proven and compatible, or deferred
67 to the 2.4-stable release if they cannot be incorporated in the current
68 stable release due to API change requirements.
70 * The stable CVS tree should not remain unstable at any time. Atomic commits
71 aught be used to introduce code from the development version to the stable
72 tree. At any given time a security release may be in preparation,
73 unbeknownst to other contributors. At any given time, testers may be
74 checking out CVS head to confirm that a bug has been corrected. And as
75 all code was well-tested in development prior to committing to the stable
76 tree, there is really no reason for this tree to be broken for more than
77 a few minutes during a lengthy commit.
79 In order to avoid 'skipped' release numbers in the stable releases, the
80 Release Manager will generally roll a release candidate (APACHE_#_#_#_RC#)
81 tag. Release Candidate tarballs will be announced to the
82 stable-testers@httpd.apache.org for the stable tree. Then, the participants
83 will vote on the quality of the proposed release tarball.
85 The final APACHE_#_#_# tag will not exist until the APACHE_#_#_#_RC# candidate
86 has passed the usual votes to release that version. Only then is the final
87 tarball packaged, removing all -rc# designations from the version number, and
88 tagging the tree with the release number.
90 DEVELOPMENT RELEASES, 2.{odd}.{revision}
91 -----------------------------------------
93 All odd numbered releases designate the 'next' possible stable release,
94 therefore the current development version will always be one greater than
95 the current stable release. Work proceeds on development releases, permitting
96 the modification of the MMN at any time in order to correct deficiencies
97 or shortcomings in the API. This means that modules from one development
98 release to another may not be binary compatible, or may not successfully
99 compile without modification to accomodate the API changes.
101 The only 'supported' development release at any time will be the most
102 recently released version. Developers will not be answering bug reports
103 of older development releases once a new release is available. It becomes
104 the resposibility of the reporter to use the latest development version
105 to confirm that any issue still exists.
107 Any new code, new API features or new ('experimental') modules may be
108 promoted at any time to the next stable release, by a vote of the project
109 contributors. This vote is based on the technical stability of the new
110 code and the stability of the interface. Once moved to stable, that feature
111 cannot change for the remainder of that stable release cycle, so the vote must
112 reflect that the final decisions on the behavior and naming of that new
113 feature were reached. Vetos continue to apply to this choice of introducing
114 the new work to the stable version.
116 At any given time, when the quality of changes to the development branch
117 is considered release quality, that version may become a candidate for the
118 next stable release. This includes some or all of the API changes, promoting
119 experimental modules to stable or deprecating and eliminating older modules
120 from the last stable release. All of these choices are considered by the
121 project as a group in the interests of promoting the stable release, so that
122 any given change may be 'deferred' for a future release by the group, rather
123 than introduce unacceptable risks to adopting the next stable release.
125 Third party module authors are strongly encouraged to test with the latest
126 development version. This assures that the module will be ready for the next
127 stable release, but more importantly, the author can react to shortcomings
128 in the API early enough to warn the dev@httpd.apache.org community of the
129 shortcomings so that they can be addressed before the stable release. The
130 entire burden is on the module author to anticipate the needs of their module
131 before the stable release is created. Once a new stable release cycle has
132 begun, that API will be present for the lifetime of the stable release. Any
133 desired changes in the stable versions must wait for inclusion into the next
136 When deciding to promote a development tree to being stable, a determination
137 should be made whether the changes since the last stable version warrant a
138 major version bump. That is, if 2.2 is the current stable version and 2.3 is
139 'ready' to become stable, the group needs to decide if the next stable
140 version is 2.4 or 3.0. One suggested rule of thumb is that if it requires
141 too much effort to port a module from 2.2 to 2.4, then the stable version
142 should be labeled 3.0.
144 In order to ease the burden of creating development releases, the process
145 for packaging a development releases is less formal than for the stable
146 release. This strategy reflects the fact that while in development, versions
147 are cheap. Development releases may be classified as alpha, beta, or GA
148 to reflect the group's perceived stability of the tree. Development releases
149 may be made at any time by any committer.
151 Please read the following link for a more detailed description of the
152 development release strategy:
154 http://httpd.apache.org/dev/release.html
160 * Source code should follow style guidelines.
161 OK, we all agree pretty code is good. Probably best to clean this
162 up by hand immediately upon branching a 2.1 tree.
163 Status: Justin volunteers to hand-edit the entire source tree ;)
166 Recall when the release plan for 2.0 was written:
167 Absolute Enforcement of an "Apache Style" for code.
168 Watch this slip into 3.0.
171 The style guide needs to be reviewed before this can be done.
172 http://httpd.apache.org/dev/styleguide.html
173 The current file is dated April 20th 1998!
176 It's survived since '98 because it's welldone :-) Suggest we
177 simply follow whatever is documented in styleguide.html as we
178 branch the next tree. Really sort of straightforward, if you
179 dislike a bit within that doc, bring it up on the dev@httpd
180 list prior to the next branch.
182 So Bill sums up ... let's get the code cleaned up in CVS head.
183 Remember, it just takes cvs diff -b (that is, --ignore-space-change)
184 to see the code changes and ignore that cruft. Get editing Justin :)
186 * revamp the input filter syntax to provide for ordering of
187 filters created with the Set{Input|Output}Filter and the
188 Add{Input|Output}Filter directives. A 'relative to filterx'
189 syntax is definately preferable.
191 * Platforms that do not support fork (primarily Win32 and AS/400)
192 Architect start-up code that avoids initializing all the modules
193 in the parent process on platforms that do not support fork.
195 . Better yet - not only inform the startup of which phase it's in,
196 but allow the parent 'process' to initialize shared memory, etc,
197 and create a module-by-module stream to pass to the child, so the
198 parent can actually arbitrate the important stuff.
200 * Replace stat [deferred open] with open/fstat in directory_walk.
201 Justin, Ian, OtherBill all interested in this. Implies setting up
202 the apr_file_t member in request_rec, and having all modules use
203 that file, and allow the cleanup to close it [if it isn't a shared,
206 * The Async Apache Server implemented in terms of APR.
207 [Bill Stoddard's pet project.]
208 Message-ID: <008301c17d42$9b446970$01000100@sashimi> (dev@apr)
210 OtherBill notes that this can proceed in two parts...
212 Async accept, setup, and tear-down of the request
213 e.g. dealing with the incoming request headers, prior to
214 dispatching the request to a thread for processing.
215 This doesn't need to wait for a 2.x/3.0 bump.
217 Async delegation of the entire request processing chain
218 Too many handlers use stack storage and presume it is
219 available for the life of the request, so a complete
220 async implementation would need to happen 3.0 release.
222 * Add a string "class" that combines a char* with a length
223 and a reference count. This will help reduce the number
224 of strlen and strdup operations during request processing.
225 Including both the length and allocation will save us a ton
226 of reallocation we do today, in terms of string manipulation.
228 OtherBill asks if this is really an APR issue, not an HTTPD issue?
231 MAKING APACHE REPOSITORY-AGNOSTIC
232 (or: remove knowledge of the filesystem)
234 [ 2002/10/01: discussion in progress on items below; this isn't
237 * dav_resource concept for an HTTP resource ("ap_resource")
239 * r->filename, r->canonical_filename, r->finfo need to
240 disappear. All users need to use new APIs on the ap_resource
243 (backwards compat: today, when this occurs with mod_dav and a
244 custom backend, the above items refer to the topmost directory
245 mapped by a location; e.g. docroot)
247 Need to preserve a 'filename'-like string for mime-by-name
248 sorts of operations. But this only needs to be the name itself
251 Justin: Can we leverage the path info, or do we not trust the
254 gstein: well, it isn't the "path info", but the actual URI of
255 the resource. And of course we trust the user... that is
256 the resource they requested.
258 dav_resource->uri is the field you want. path_info might
259 still exist, but that portion might be related to the
260 CGI concept of "path translated" or some other further
263 To continue, I would suggest that "path translated" and
264 having *any* path info is Badness. It means that you did
265 not fully resolve a resource for the given URI. The
266 "abs_path" in a URI identifies a resource, and that
267 should get fully resolved. None of this "resolve to
268 <here> and then we have a magical second resolution
269 (inside the CGI script)" or somesuch.
271 Justin: Well, let's consider mod_mbox for a second. It is sort of
272 a virtual filesystem in its own right - as it introduces
273 it's own notion of a URI space, but it is intrinsically
274 tied to the filesystem to do the lookups. But, for the
275 portion that isn't resolved on the file system, it has
276 its own addressing scheme. Do we need the ability to
279 * The translate_name hook goes away
281 Wrowe altogether disagrees. translate_name today even operates
282 on URIs ... this mechansim needs to be preserved.
284 * The doc for map_to_storage is totally opaque to me. It has
285 something to do with filesystems, but it also talks about
286 security and per_dir_config and other stuff. I presume something
287 needs to happen there -- at least better doc.
289 Wrowe agrees and will write it up.
291 * The directory_walk concept disappears. All configuration is
292 tagged to Locations. The "mod_filesystem" module might have some
293 internal concept of the same config appearing in multiple
294 places, but that is handled internally rather than by Apache
297 Wrowe suggests this is wrong, instead it's private to filesystem
298 requests, and is already invoked from map_to_storage, not the core
299 handler. <Directory > and <Files > blocks are preserved as-is,
300 but <Directory > sections become specific to the filesystem handler
301 alone. Because alternate filesystem schemes could be loaded, this
302 should be exposed, from the core, for other file-based stores to
303 share. Consider an archive store where the layers become
304 <Directory path> -> <Archive store> -> <File name>
306 Justin: How do we map Directory entries to Locations?
308 * The "Location tree" is an in-memory representation of the URL
309 namespace. Nodes of the tree have configuration specific to that
310 location in the namespace.
315 const char *name; /* name of this node relative to parent */
317 struct ap_conf_vector_t *locn_config;
319 apr_hash_t *children; /* NULL if no child configs */
322 The following config:
324 <Location /server-status>
325 SetHandler server-status
331 Creates a node with name=="server_status", and the node is a
332 child of the "/" node. (hmm. node->name is redundant with the
333 hash key; maybe drop node->name)
335 In the config vector, mod_access has stored its Order, Deny, and
336 Allow configs. mod_core has stored the SetHandler.
338 During the Location walk, we merge the config vectors normally.
340 Note that an Alias simply associates a filesystem path (in
341 mod_filesystem) with that Location in the tree. Merging
342 continues with child locations, but a merge is never done
343 through filesystem locations. Config on a specific subdir needs
344 to be mapped back into the corresponding point in the Location
345 tree for proper merging.
347 * Config is parsed into a tree, as we did for the 2.0 timeframe,
348 but that tree is just a representation of the config (for
349 multiple runs and for in-memory manipulation and usage). It is
350 unrelated to the "Location tree".
352 * Calls to apr_file_io functions generally need to be replaced
353 with operations against the ap_resource. For example, rather
354 than calling apr_dir_open/read/close(), a caller uses
355 resource->repos->get_children() or somesuch.
357 Note that things like mod_dir, mod_autoindex, and mod_negotation
358 need to be converted to use these mechanisms so that their
359 functions will work on logical repositories rather than just
362 * How do we handle CGI scripts? Especially when the resource may
363 not be backed by a file? Ideally, we should be able to come up
364 with some mechanism to allow CGIs to work in a
365 repository-independent manner.
367 - Writing the virtual data as a file and then executing it?
368 - Can a shell be executed in a streamy manner? (Portably?)
369 - Have an 'execute_resource' hook/func that allows the
370 repository to choose its manner - be it exec() or whatever.
371 - Won't this approach lead to duplication of code? Helper fns?
373 gstein: PHP, Perl, and Python scripts are nominally executed by
374 a filter inserted by mod_php/perl/python. I'd suggest
375 that shell/batch scripts are similar.
377 But to ask further: what if it is an executable
378 *program* rather than just a script? Do we yank that out
379 of the repository, drop it onto the filesystem, and run
382 I'll vote -0.9 for CGIs as a filter. Keep 'em handlers.
384 Justin: So, do we give up executing CGIs from virtual repositories?
385 That seems like a sad tradeoff to make. I'd like to have
386 my CGI scripts under DAV (SVN) control.
388 * How do we handle overlaying of Location and Directory entries?
389 Right now, we have a problem when /cgi-bin/ is ScriptAlias'd and
390 mod_dav has control over /. Some people believe that /cgi-bin/
391 shouldn't be under DAV control, while others do believe it
392 should be. What's the right strategy?