XP Versions

  Status: implemented,  Mon Nov 27 21:33:54 2006
  • Created: 2006-11-23 15:48:08+0100
  • Categories: <core>
  • Author: friebe
  • Contributors: kiesel

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: 

  . RFC #0005: Add method ClassLoader::defineClass()
  . RFC #0011: Changes to Peer/DataSet/Criteria API
  . RFC #0014: Add core function raise()

3.0.0, released 2005-03-01: 

  . RFC #0016: Method and class annotations 
  . RFC #0017: Webservices metadata
  . RFC #0020: Unit tests metadata

3.0.1, released 2005-03-31: 

  . RFC #0021: 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: 

  . RFC #0025: 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: 

  RFC #0019: LDAP query infrastructure

3.0.5, released 2005-09-01: 

  . RFC #0032: Add annotations for Unittest API
  . RFC #0033: Annotation support for members / lang.reflect.Field
  . RFC #0035: Interceptors for FTP storage

3.0.6, released 2005-09-28: 

  . RFC #0030: Overloaded methods in lang.reflect.Proxy

3.0.7, released 2005-10-07: 

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

3.0.8, released 2005-11-11: 

  . RFC #0040: Annotation-based XML marshalling/unmarshalling
  . SVN rev. 6100 - MORE POWER!

3.1.0, released 2005-11-29: 

  . RFC #0028: Add a method forwardTo() to XMLScriptletResponse
  . RFC #0042: SOAP Headers API
  . RFC #0043: 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: 

  . RFC #0044: New save() method in DataSet

3.2.0, released 2005-12-21: 

  . RFC #0012: EJB access API
  . RFC #0038: Type wrappers
  . RFC #0045: Unique multiple occurrences of errors
  . RFC #0047: Guaranteed destructor calls
  . RFC #0048: 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: 

  . RFC #0050: RDBMS Criteria API enhancement
  . RFC #0053: Formresult information about a wrapper

3.2.2, released 2006-05-14: 

  . RFC #0055: Make xp::stringOf() fatal error safe
  . RFC #0056: Grand unified RPC api
  . RFC #0057: Collections framework

3.2.3, released 2006-06-30: 

  . RFC #0058: New rdbms exception
  . RFC #0059: Timeouts for unit tests
  . Unittests: Fix assertEquals() and assertNotEquals() for arrays

3.2.4, released 2006-07-07: 

  . RFC #0066: TCP_NODELAY server option

3.3.0, released 2006-08-25: 

  . RFC #0065: Server Protocol API
  . RFC #0067: Add debug logging to remote API
  . RFC #0070: Extend ClassLoader::defineClass() 
  . RFC #0071: Class / Classloader associations

3.4.0, released 2006-09-20: 

  . RFC #0073: Change toString() to use xp::stringOf()

3.5.0, released 2006-10-11: 

  . RFC #0074: Support for class loading from class archives in the core

3.5.1, released 2006-10-25: 

  . RFC #0086: Exclude common trace elements from ChainedException's trace

3.6.0, released 2006-11-10: 

  . RFC #0085: Make lang.Throwable::toString() easily overwriteable
  . RFC #0089: Core functions ref() and deref()

4.0.0, released 2006-11-20: 

  . RFC #0084: 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). <EOF>


Table of contents