Policies/New KDE Library API Policy - Revision history

Seli: /* Use of Experimental API in Applications */

2009-12-10T16:04:56Z

‎Use of Experimental API in Applications

Bille: Fix typos

2009-07-06T18:06:32Z

Fix typos

Aseigo: /* Making the Transition to Stable Releases */

2009-06-27T15:33:46Z

‎Making the Transition to Stable Releases

Aseigo: /* Namespace Recommendation */

2009-06-27T15:32:53Z

‎Namespace Recommendation

Aseigo: /* Source Code */

2009-06-26T20:28:23Z

‎Source Code

Aseigo: /* Source Code */

2009-06-26T20:22:25Z

‎Source Code

Aseigo: /* Library Naming */

2009-06-26T20:20:29Z

‎Library Naming

Aseigo at 20:18, 26 June 2009

2009-06-26T20:18:42Z

Aseigo: /* Rational */

2009-06-26T20:14:20Z

‎Rational

Aseigo: /* Source Code */

2009-06-26T20:12:01Z

‎Source Code

← Older revision		Revision as of 16:04, 10 December 2009
Line 46:		Line 46:

	While an API is marked as experimental, usage by applications should in most cases be limited to applications that ship as part of the KDE Software Distribution. This makes it easier on packagers and distributors to work with us when it comes time to migrate from one version of the experimental lib to another or when it gets merged into kdelibs proper.		While an API is marked as experimental, usage by applications should in most cases be limited to applications that ship as part of the KDE Software Distribution. This makes it easier on packagers and distributors to work with us when it comes time to migrate from one version of the experimental lib to another or when it gets merged into kdelibs proper.
		+
		+	Note that not only the API is considered experimental, but all aspects of the functionality (D-Bus interfaces used internally, etc.). Therefore using such experimental API in applications that do not ship as part of the KDE Software Distribution means that the functionality can break with any update.

	== Making the Transition to Stable Releases ==		== Making the Transition to Stable Releases ==

@@ Line 1: / Line 1: @@
-== Rational ==
+== Rationale ==
 From time to time it becomes apparent that new API needs to be added to KDE's libraries in kdelibs, kdepimlibs, etc. It may be in the form of new classes to existing libraries or entirely new libraries altogether.
@@ Line 11: / Line 11: @@
 == Source Code ==
-For API destined for inclusion in kdelibs, the source code should appear in {{path|trunk/KDE/kdelibs/experimental}} in it's own subdirectory. It needs to be able to be built as an independent project from within its directory there.
+For API destined for inclusion in kdelibs, the source code should appear in {{path|trunk/KDE/kdelibs/experimental}} in its own subdirectory. It needs to be able to be built as an independent project from within its directory there.
 [[../ExperimentalKDELibsCMakeLists.txt|An example CMakeLists.txt file can be found here]]

← Older revision		Revision as of 15:33, 27 June 2009
Line 50:		Line 50:

	Once there is reasonable confidence in the ABI and API of the new library or class(es), which may take one release or several to accomplish, and the code meets the other requirements of library code such as API documentation, then the library may be moved into kdelibs (or into the appropriate library in the case of classes) and no further independent releases are required.		Once there is reasonable confidence in the ABI and API of the new library or class(es), which may take one release or several to accomplish, and the code meets the other requirements of library code such as API documentation, then the library may be moved into kdelibs (or into the appropriate library in the case of classes) and no further independent releases are required.
		+
		+	Any namespace used marking the code as experimental should be removed, and this will avoid symbol name collisions with applications that haven't yet updated away from the experimental library.

	Out of consideration, application developers should be given reasonable notice of this transition via appropriate mailing lists or other communication channels.		Out of consideration, application developers should be given reasonable notice of this transition via appropriate mailing lists or other communication channels.

@@ Line 33: / Line 33: @@
 If the code is still experimental and/or intended for inclusion in one of the existing KDE libraries, consider using the Experimental C++ namespace for the public classes. This will help remind application developers using this library that it is subject to change.
-This is not, however, required.
+This is strongly recommend though not strictly required.
 == Releases ==

@@ Line 13: / Line 13: @@
 For API destined for inclusion in kdelibs, the source code should appear in {{path|trunk/KDE/kdelibs/experimental}} in it's own subdirectory. It needs to be able to be built as an independent project from within its directory there.
-[[CMakeLists.txt|An example CMakeLists.txt file can be found here]]
+[[../ExperimentalKDELibsCMakeLists.txt|An example CMakeLists.txt file can be found here]]
 == Library Naming ==

← Older revision		Revision as of 20:22, 26 June 2009
Line 12:		Line 12:

	For API destined for inclusion in kdelibs, the source code should appear in {{path\|trunk/KDE/kdelibs/experimental}} in it's own subdirectory. It needs to be able to be built as an independent project from within its directory there.		For API destined for inclusion in kdelibs, the source code should appear in {{path\|trunk/KDE/kdelibs/experimental}} in it's own subdirectory. It needs to be able to be built as an independent project from within its directory there.
		+
		+	[[CMakeLists.txt\|An example CMakeLists.txt file can be found here]]

	== Library Naming ==		== Library Naming ==

← Older revision		Revision as of 20:20, 26 June 2009
Line 18:		Line 18:

	This allows application developers to use the library without concerns of random application breakage due to upgrading the library.		This allows application developers to use the library without concerns of random application breakage due to upgrading the library.
		+
		+	Also remember to version the library symbols; this can be done in the CMakeLists.txt file with "set_target_properties(greatness-1 PROPERTIES VERSION 1.0.0 SOVERSION 1)", replacing the various names and version numbers as appropriate.

	== Header Installation ==		== Header Installation ==

@@ Line 34: / Line 34: @@
 A buildable tarball of the library must be released either before or in tandem with the KDE release in which applications are intended to use it. A tag should also be created marking the release.
 == Making the Transition to Stable Releases ==
-Once there is reasonable confidence in the ABI and API of the new library or class(es), which may take one release or several to accomplish, then the library may be moved into kdelibs (or into the appropriate library in the case of classes) and no further independent releases are required.
+Once there is reasonable confidence in the ABI and API of the new library or class(es), which may take one release or several to accomplish, and the code meets the other requirements of library code such as API documentation, then the library may be moved into kdelibs (or into the appropriate library in the case of classes) and no further independent releases are required.
 Out of consideration, application developers should be given reasonable notice of this transition via appropriate mailing lists or other communication channels.

@@ Line 5: / Line 5: @@
 However, the main KDE library modules have strict binary and source compatibility guarantees and it is nearly impossible to get an API perfect on the first round and without real world application usage. This is doubly true for API which results in changes to the user experience (e.g. new user interface elements, changes in workflow, etc.)
-For this reason, unless the new class(es) or library are of a provably right nature (which usually means they fall into the realm of "trivial additions"), it is wise to release an experimental version of the classes as a separate library for use by applications before they find their way into an official KDE library release.
+For this reason, unless the new class(es) or library are of a provably right nature (which usually means they fall into the realm of "trivial additions") or have been released with prior KDE releases as part of another module (and so have been tested and proven in practice), it is wise to release an experimental version of the classes as a separate library for use by applications before they find their way into an official KDE library release.
 This policy describes what is currently considered as the best practice approach in such situations.