thekid/rfc — Issue #91: RFC 0091: XP Versions 
Author: thekid
Created: 2011-10-09 15:00:23+00:00
State: open

Scope of Change
====
The XP framework will have a version number and versioning guidelines.
This version number will be present in the XP's runtime XAR's filename.

Rationale
====
To easily be able to see when the framework changes.

Functionality
====

Basics
----
The version number will consist of three parts:

```
X.X.X
^ ^ ^
| | Patch-level
| Minor version
Major version

```

Storage
----
The current version number is stored in a file in xp/trunk called
VERSION.

XARs
----
For every version number starting as of version 4.0.0, a list of XARs
will be created containing the version number in their filenames.

* xp-rt-4.0.0.xar (skeleton/*)
* org.gnome-4.0.0.xar (ports/classes/org/gnome/*)
* com.sun-4.0.0.xar (ports/classes/com/sun/*)
(etc.)

It is guaranteed that files from exact versions will always work
together flawlessly.

Patch-level versions will also be interopable, but minor versions
may already introduce new inter-package dependencies and thus xars
from one minor version may or may not work together. If xars from
one major versions work together with another version it's only
because you're lucky:)

Guidelines for version numbers
----
Definition: The XP framework's core is lang.base.php, lang, io and util.

* The major version number is changed whenever incompatible changes
to the core occur (e.g. a new core functionality such as ref()/deref())
or when a new way of doing things is introduced (e.g. annotations,
xars).

* The minor version number is changed whenever new APIs inside the
core are created (e.g. lang.types, util.collections) or when other
important APIs (rdbms, remote, unittest, io, webservices) are changed.

The minor version number is also changed if a new API is being used
by a different package (e.g., if the io.collections API is used by
org.gnome classes).

* The patch-level is increased whenever changes to non-core are made,
important bug fixes are released, new APIs are created.

In cases where one is unsure, the procedure should be discussed on the
developer's mailing list.

Version history
----
0.0.1, released 2002-02-21:

```
. Initial revision:
A /trunk/doc
A /trunk/doc/skeleton
A /trunk/doc/skeleton/cart.php
A /trunk/doc/skeleton/domain
A /trunk/doc/skeleton/domain/getdescr.php
A /trunk/doc/skeleton/domain/isfree.test.php
A /trunk/doc/skeleton/domain/sybinit.err
A /trunk/doc/skeleton/net
A /trunk/doc/skeleton/net/portal.php
A /trunk/doc/skeleton/order.php
A /trunk/doc/skeleton/order_idea.php
A /trunk/doc/skeleton/trycatch.php
A /trunk/doc/skeleton/xpath.php
A /trunk/doc/skeleton/xpath.xml
A /trunk/skeleton
A /trunk/skeleton/lang
A /trunk/skeleton/lang/Exception.class.php
A /trunk/skeleton/lang/Object.class.php
A /trunk/skeleton/lang.base.php
A /trunk/skeleton/net
A /trunk/skeleton/net/NetException.class.php
A /trunk/skeleton/net/Socket.class.php
A /trunk/skeleton/net/ftp
A /trunk/skeleton/net/ftp/FTPConnect.class.php
A /trunk/skeleton/net/http
A /trunk/skeleton/net/http/HTTPRequest.class.php
A /trunk/skeleton/net/session
A /trunk/skeleton/net/session/ToolSession.class.php
A /trunk/skeleton/rdbms
A /trunk/skeleton/rdbms/DBConnectionPool.class.php
A /trunk/skeleton/rdbms/sybase
A /trunk/skeleton/rdbms/sybase/SPSybase.class.php
A /trunk/skeleton/util
A /trunk/skeleton/util/Binford.class.php
A /trunk/skeleton/util/LOG.class.php
A /trunk/skeleton/util/Properties.class.php
A /trunk/skeleton/util/cmd
A /trunk/skeleton/util/cmd/SingleProcess.class.php
A /trunk/skeleton/xml
A /trunk/skeleton/xml/Node.class.php
A /trunk/skeleton/xml/OutputDocument.class.php
A /trunk/skeleton/xml/Tree.class.php
A /trunk/skeleton/xml/XML.class.php
A /trunk/skeleton/xml/XMLParser.class.php
A /trunk/skeleton/xml/XPath.class.php
A /trunk/skeleton/xml/XSLProcessor.class.php
A /trunk/skeleton/xml/XSelect.class.php
A /trunk/skeleton/xml/editor
A /trunk/skeleton/xml/editor/Part.class.php
A /trunk/skeleton/xml/form
A /trunk/skeleton/xml/form/Wizard.class.php
A /trunk/skeleton/xml/soap
A /trunk/skeleton/xml/soap/SOAPEnvelope.class.php
A /trunk/skeleton/xml/soap/SOAPRequestFactory.class.php
A /trunk/skeleton/xml/soap/SOAPSyncRequest.class.php
A /trunk/skeleton/xml/soap/WSDLNode.class.php

```

0.1.0, released 2002-03-27:

```
. import --> uses

```

0.2.0, released 2002-05-07:

```
. util.log.API
. Core functionality cast()
. rdbms APIs return datetimes as Date objects

```

0.2.1, released 2002-06-28:

```
. Various util.Properties enhancements
create()
exists()
reset()
readArray()
readFloat()
hasSection()
writeSection()
writeString()
writeInteger()
writeFloat()
writeBool()
writeArray()
writeComment()

```

0.2.2, released 2002-10-20:

```
. New Imaging API

```

0.3.0, released 2002-11-12:

```
. Initial revision of lang.XPClass

```

0.4.0, released 2002-12-10:

```
. rdbms API: DSNs
. Add finally()

```

0.4.1, released 2003-02-17:

```
. Remove long-time deprecated util.LOG class

```

0.5.0, released 2003-04-25:

```
. Use var_export() instead of serialize in default toString method to
make a more readable presentation

```

0.6.0, relased 2003-05-25:

```
. rdbms APIs: Add support for persistent connections
. rdbms APIs: Remove affected() and numrows()
. lang.Thread: Initial release
. Make XPClass::newInstance pass arguments to new

```

0.6.0, released 2003-06-01:

```
. Unittest API
. Implement debug_backtrace support for exceptions

```

0.7.0, released 2003-06-09:

```
. util.Date::isBefore() and isAfter() methods

```

1.0.0, released 2003-06-23:

```
. No more support for PHP < 4.3.0
. There is now a common subclass for Errors and Exceptions called Throwable
. An exceptions stacktrace is an array of lang.StackTraceElement objects
. Exception::getStackTrace() returns this array and no longer a string
. Removes Object::getName() which has been deprecated for a while now
. Uses xp::registry to keep the global namespace free of bullshit

```

1.0.1, released 2003-06-26:

```
. Show max. up until the first \n in exception stacktraces

```

1.0.2, released 2003-07-10:

```
. rename [Database].class.php into [Database]Connection.class.php

```

1.1.0, released 2003-08-25:

```
. lang.NullPointerException - initial release
. Add the core feature of SAPIs

```

1.2.0, released 2003-09-14:

```
. Add xp::typeOf core functionality
. Add core functionality xp::gc()
. Remove (unused) lang.ExternalClassLoader
. Add file.separator and path.separator system properties
. Prefix transactions with "xp_" so there is no problem
with reserved words.

```

2.0.0, released 2003-09-21:

```
. Implement interfaces
. Remove check for debug_backtrace() existance (requires 4.2 compat SAPI)
. Add method hashCode() which will return a unique id for every object
. Add method equals()
. Add method clone()
. util.Configurable, util.log.Traceable interfaces
. Made RuntimeException an Error

```

2.0.1, released 2003-09-27:

```
. Newly introduced SQLConnectException, SQLStateException and
SQLStatementFailedException, all being subclasses of SQLException

```

2.1.0, released 2003-10-18:

```
. Introduce core function "delete"

```

2.2.0, released 2003-11-16:

```
. Add "with" syntactic sugar.

```

2.2.1, released 2004-01-04:

```
. rdbms APIs: prepare("where news_id in (%d)", array(1, 2, 3)) will
result in "where news_id in (1, 2, 3)"

```

2.3.0, released 2004-01-16:

```
. Remove ability to use ClassLoader statically
. Change XPClass::getMethods() to return an array of lang.Method objects
. Change XPClass::getMethods() not to return constructor and destructor
. Add method XPClass::getConstructor()
. Fix XPClass::getParentclass() so that it returns NULL if there is no parent
. Add method XPClass::isSubclassOf()
. Add method XPClass::isInstance()
. Add method XPClass::isInterface()
. Add method XPClass::getInterfaces()
. Add core functionality xp::null()

```

2.3.1, released 2004-03-02:

```
. Add method ClassLoader::findClass()

```

2.4.0, released 2004-04-10:

```
. Add support for inheriting interfaces
. Use the tokenizer to accomplish full-featured method reflection
. getModifiers() - returns a bitfield of modifiers (public, private, protected,
abstract, final, static)
. getModifierNames() - same, but as an array of strings.
. getArguments() - returns an array of method arguments (lang.reflect.Argument)
. getReturnType() - returns the return type as string
. getExceptionNames() - returns thrown exceptions as an array of fully
qualified class names
. getExceptionTypes() - same, but as an array of lang.XPClass objects

```

2.5.0, released 2004-04-18:

```
. Make uses() fail with a fatal error in case one of the classes in
its list is not found (or can not be loaded due to other reasons).

```

2.5.1, released 2004-05-13:

```
. Fix rdbms statement tokenizer for %% or unknown tokens (e.g. %X)

```

2.6.0, released 2004-06-07:

```
. Remove Object::__construct(), it is deprecated for forward compatibility
reasons

```

2.6.1, released 2004-07-06:

```
. Remove Object::clone() in favor of new core functionality clone()
. Add method hasConstructor()
. Return NULL from getConstructor() if no constructor exists

```

2.6.2, released 2004-07-16:

```
. DBConnection now extends util.Observable, no longer implements util.Traceable,
util.log.LogObserver is introduced to be an Observer that log the database
activity.

```

2.7.0, released 2004-08-31:

```
. Support static initializers in classes.

```

2.7.1, released 2004-09-21:

```
. Add support for dates beyond unix timestamp

```

2.8.0, released 2004-11-10:

```
. Add core function xp::stringOf()

```

2.9.0, released 2005-01-25:

```
. xp-framework/rfc #5: Add method ClassLoader::defineClass()
. xp-framework/rfc #11: Changes to Peer/DataSet/Criteria API
. xp-framework/rfc #14: Add core function raise()

```

3.0.0, released 2005-03-01:

```
. xp-framework/rfc #16: Method and class annotations
. xp-framework/rfc #17: Webservices metadata
. xp-framework/rfc #20: Unit tests metadata

```

3.0.1, released 2005-03-31:

```
. xp-framework/rfc #21: Add support for multi-line annotations

```

3.0.2, released 2005-04-08:

```
. lang.reflect.Proxy: First useable release

```

3.0.3, released 2005-05-29:

```
. xp-framework/rfc #25: Replace text.apidoc with new API
. Add method Method::getArgument() which retrieves an argument by a given position
. Add method Method::numArguments() which returns the number of arguments

```

3.0.4, released 2005-07-20:

```
xp-framework/rfc #19: LDAP query infrastructure

```

3.0.5, released 2005-09-01:

```
. xp-framework/rfc #32: Add annotations for Unittest API
. xp-framework/rfc #33: Annotation support for members / lang.reflect.Field
. xp-framework/rfc #35: Interceptors for FTP storage

```

3.0.6, released 2005-09-28:

```
. xp-framework/rfc #30: Overloaded methods in lang.reflect.Proxy

```

3.0.7, released 2005-10-07:

```
. xp-framework/rfc #39: Decode username/password when using parse_url() in framework
. net.xp-framework => net.xp_framework

```

3.0.8, released 2005-11-11:

```
. xp-framework/rfc #40: Annotation-based XML marshalling/unmarshalling
. SVN rev. 6100 - MORE POWER!

```

3.1.0, released 2005-11-29:

```
. xp-framework/rfc #28: Add a method forwardTo() to XMLScriptletResponse
. xp-framework/rfc #42: SOAP Headers API
. xp-framework/rfc #43: UnknownRemoteObject
. Bail when magic_quotes_gpc setting is on
. XPClass->toString() output changes
. Make regular expression parse generic types

```

3.1.1, released 2005-12-09:

```
. xp-framework/rfc #44: New save() method in DataSet

```

3.2.0, released 2005-12-21:

```
. xp-framework/rfc #12: EJB access API
. xp-framework/rfc #38: Type wrappers
. xp-framework/rfc #45: Unique multiple occurrences of errors
. xp-framework/rfc #47: Guaranteed destructor calls
. xp-framework/rfc #48: ESDL - Enterprise Service Description Language
. catch AssertionFailedErrors which might be thrown in the setUp() method of a
testcase in addition to the PrerequisitesNotMetError.
Tests may include common assertions which can be moved to setUp() then.
. Fix PHP4.4.x E_NOTICEs about variables and references

```

3.2.1, released 2006-01-30:

```
. xp-framework/rfc #50: RDBMS Criteria API enhancement
. xp-framework/rfc #53: Formresult information about a wrapper

```

3.2.2, released 2006-05-14:

```
. xp-framework/rfc #55: Make xp::stringOf() fatal error safe
. xp-framework/rfc #56: Grand unified RPC api
. xp-framework/rfc #57: Collections framework

```

3.2.3, released 2006-06-30:

```
. xp-framework/rfc #58: New rdbms exception
. xp-framework/rfc #59: Timeouts for unit tests
. Unittests: Fix assertEquals() and assertNotEquals() for arrays

```

3.2.4, released 2006-07-07:

```
. xp-framework/rfc #66: TCP_NODELAY server option

```

3.3.0, released 2006-08-25:

```
. xp-framework/rfc #65: Server Protocol API
. xp-framework/rfc #67: Add debug logging to remote API
. xp-framework/rfc #70: Extend ClassLoader::defineClass()
. xp-framework/rfc #71: Class / Classloader associations

```

3.4.0, released 2006-09-20:

```
. xp-framework/rfc #73: Change toString() to use xp::stringOf()

```

3.5.0, released 2006-10-11:

```
. xp-framework/rfc #74: Support for class loading from class archives in the core

```

3.5.1, released 2006-10-25:

```
. xp-framework/rfc #86: Exclude common trace elements from ChainedException's trace

```

3.6.0, released 2006-11-10:

```
. xp-framework/rfc #85: Make lang.Throwable::toString() easily overwriteable
. xp-framework/rfc #89: Core functions ref() and deref()

```

4.0.0, released 2006-11-20:

```
. xp-framework/rfc #84: Packages cleanup

```

Security considerations
====
None.

Speed impact
====
None.

Dependencies
====
None.

Related documents
====
- http://apr.apache.org/versioning.html
APR's Version Numbering

- http://developer.gnome.org/gep/gep-4.html
Module versioning and branching guidelines for GNOME platform

- http://wiki.eclipse.org/index.php/Version_Numbering
Eclipse Version Numbering

- http://pear.php.net/group/docs/20040226-vn.php
PEAR Group - Administrative Documents - Version Naming

- http://en.wikipedia.org/wiki/Linux_kernel#Version_numbering
Linux (kernel) Version Numbering

- http://developer.mozilla.org/en/docs/Extension_Versioning%2C_Update_and_Compatibility
MozDev: Extension Versioning, Update and Compatibility

Comments
====
- friebe, Thu Nov 23 18:07:09 CET 2006
Should we store the version history in xp/trunk/HISTORY? Or in
xp/trunk/Changelog?

- friebe, Thu Nov 23 18:32:46 CET 2006
An idea would be to add whether an RFC will change the framework's version
number to the "Dependencies" section.

- friebe, Thu Nov 23 18:37:28 CET 2006
Should we have a target version as @target in RFCs?

- friebe, Thu Nov 23 18:34:04 CET 2006
To give ports/classes a level of independency but also to make it clear
which framework version they belong to, we could add a release number to
their versions, e.g.

org.gnome-4.0.0_1.xar (works with 4.0.0 of framework and is release #1)
org.gnome-4.0.0_2.xar (works with 4.0.0 of framework and is release #2)

- friebe, Thu Nov 23 18:37:01 CET 2006
Should we have dedicated roadmaps for each release?

- kiesel, Fri Nov 24 16:39:31 CET 2006
Adding util/ to the core but not io/ seems inconsistent. Either we should
declare the core as what is absolutely needed to boot XP or we open
up the core for util *and* io (and possibly more).

- friebe, Thu Aug 20 09:22:14 2009
Added @target to RFCs