2006-11-07 Havoc Pennington <hp@redhat.com>

	* doc/dbus-specification.xml, doc/dbus-faq.xml, README: various
	documentation updates. Bump faq/spec versions (not to 1.0; I don't
	think the spec will be "finished"/1.0 when we ship the 1.0 library).

6 files changed, 144 insertions, 48 deletions

diff --git a/COPYING b/COPYING
index 19a5a9a9..a91ca1d1 100644
--- a/COPYING
+++ b/COPYING
@@ -3,8 +3,8 @@ License version 2.1, or the GNU General Public License version 2.
 Both licenses are included here. Some of the standalone binaries are
 under the GPL only; in particular, but not limited to,
 tools/dbus-cleanup-sockets.c and test/decode-gcov.c. Each source code
-file is marked with the proper copyright information.
-
+file is marked with the proper copyright information - if you find a
+file that isn't marked please bring it to our attention.
 
 
 The Academic Free License
diff --git a/ChangeLog b/ChangeLog
index 5a0312bd..7acefc26 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,9 @@
+2006-11-07  Havoc Pennington  <hp@redhat.com>
+
+	* doc/dbus-specification.xml, doc/dbus-faq.xml, README: various
+	documentation updates. Bump faq/spec versions (not to 1.0; I don't
+	think the spec will be "finished"/1.0 when we ship the 1.0 library).
+
 2006-11-06  John (J5) Palmieri  <johnp@redhat.com>
 
 	* bus/bus.c: Missed patch - pass in the context to the directory watch
diff --git a/README b/README
index 77047f77..02848904 100644
--- a/README
+++ b/README
@@ -1,17 +1,64 @@
-D-BUS is a simple IPC library based on messages.
+Sections in this file describe:
+ - introduction and overview
+ - low-level vs. high-level API
+ - version numbers
+ - options to the configure script
+ - ABI stability policy
+
+Introduction
+===
+
+D-Bus is a simple system for interprocess communication and coordination.
 
-See also the file HACKING for notes of interest to developers working on D-BUS.
+The "and coordination" part is important; D-Bus provides a bus daemon that does things like:
+ - notify applications when other apps exit
+ - start services on demand
+ - support single-instance applications
 
 See http://www.freedesktop.org/software/dbus/ for lots of documentation, 
 mailing lists, etc.
 
-Note
+See also the file HACKING for notes of interest to developers working on D-Bus.
+
+If you're considering D-Bus for use in a project, you should be aware
+that D-Bus was designed for a couple of specific use cases, a "system
+bus" and a "desktop session bus." These are documented in more detail
+in the D-Bus specification and FAQ available on the web site.
+
+If your use-case isn't one of these, D-Bus may still be useful, but
+only by accident; so you should evaluate carefully whether D-Bus makes
+sense for your project.
+
+Note: low-level API vs. high-level binding APIs
 ===
 
-A core concept of the D-BUS implementation is that "libdbus" is
-intended to be a low-level API, similar to Xlib. Most programmers are
-intended to use the bindings to GLib, Qt, Python, Mono, Java, or
-whatever. These bindings have varying levels of completeness.
+A core concept of the D-Bus implementation is that "libdbus" is
+intended to be a low-level API. Most programmers are intended to use
+the bindings to GLib, Qt, Python, Mono, Java, or whatever. These
+bindings have varying levels of completeness and are maintained as
+separate projects from the main D-Bus package. The main D-Bus package
+contains the low-level libdbus, the bus daemon, and a few command-line
+tools such as dbus-launch.
+
+If you use the low-level API directly, you're signing up for some
+pain. Think of the low-level API as analogous to Xlib or GDI, and the
+high-level API as analogous to Qt/GTK+/HTML.
+
+Version numbers
+===
+
+D-Bus uses the common "Linux kernel" versioning system, where
+even-numbered minor versions are stable and odd-numbered minor
+versions are development snapshots.
+
+So for example, development snapshots: 1.1.1, 1.1.2, 1.1.3, 1.3.4
+Stable versions: 1.0, 1.0.1, 1.0.2, 1.2.1, 1.2.3
+
+All pre-1.0 versions were development snapshots.
+
+Development snapshots make no ABI stability guarantees for new ABI
+introduced since the last stable release. Development snapshots are
+likely to have more bugs than stable releases, obviously.
 
 Configuration flags
 ===
@@ -48,15 +95,9 @@ the ./configure program.
 API/ABI Policy
 ===
 
-D-BUS API/ABI and protocol necessarily remain in flux until we are
-sure it will meet the various needs it's intended to meet. This means
-we need to see some significant sample usage in the contexts of GNOME,
-KDE, desktop applications, and systemwide uses such as print queue
-monitoring, hotplug events, or whatever. We need the flexibility to
-incorporate feedback from this sample usage.
-
-Once we feel confident in the protocol and the API, we will release a 
-version 1.0. At that point, the intent is:
+Now that D-Bus has reached version 1.0, the objective is that all
+applications dynamically linked to libdbus will continue working
+indefinitely with the most recent system and session bus daemons.
 
  - The protocol will never be broken again; any message bus should 
    work with any client forever. However, extensions are possible
@@ -67,23 +108,47 @@ version 1.0. At that point, the intent is:
    it will always be possible to compile against and use the older 
    API, and apps will always get the API they expect.
 
-Until 1.0 is released, feedback that requires API changes may be
-incorporated into D-BUS. This may break the API, the ABI, the
-protocol, or all three.
+Interfaces can and probably will be _added_. This means both new
+functions and types in libdbus, and new methods exported to
+applications by the bus daemon.
+
+The above policy is intended to make D-Bus as API-stable as other
+widely-used libraries (such as GTK+, Qt, Xlib, or your favorite
+example). If you have questions or concerns they are very welcome on
+the D-Bus mailing list.
+
+NOTE ABOUT DEVELOPMENT SNAPSHOTS AND VERSIONING
+
+Odd-numbered minor releases (1.1.x, 1.3.x, 2.1.x, etc. -
+major.minor.micro) are devel snapshots for testing, and any new ABI
+they introduce relative to the last stable version is subject to
+change during the development cycle.
+
+Any ABI found in a stable release, however, is frozen.
+
+ABI will not be added in a stable series if we can help it. i.e. the
+ABI of 1.2.0 and 1.2.5 you can expect to be the same, while the ABI of
+1.4.x may add more stuff not found in 1.2.x.
+
+NOTE ABOUT STATIC LINKING
+
+We are not yet firmly freezing all runtime dependencies of the libdbus
+library. For example, the library may read certain files as part of
+its implementation, and these files may move around between versions.
 
-To avoid a huge soname, the plan is to increment the soname only
-between official stable releases, not with every development snapshot.
-Versions numbered 0.x are considered development snapshots.
+As a result, we don't yet recommend statically linking to
+libdbus. Also, reimplementations of the protocol from scratch might
+have to work to stay in sync with how libdbus behaves.
 
-Until 1.0 is released, you have to define -DDBUS_API_SUBJECT_TO_CHANGE
-just as a safety check to be sure everyone is aware of this API/ABI
-policy and has the right expectations.
+To lock things down and declare static linking and reimplementation to
+be safe, we'd like to see all the internal dependencies of libdbus
+(for example, files read) well-documented in the specification, and
+we'd like to have a high degree of confidence that these dependencies
+are supportable over the long term and extensible where required.
 
-We do need people to test the APIs, so please do use the development
-snapshots of D-BUS. They are intended to work and we do actively
-address bugs.
+NOTE ABOUT HIGH-LEVEL BINDINGS
 
-However, if you're shipping a commercial binary-only application that
-needs to keep running on M future versions of N operating systems, you
-might want to include your own copy of D-BUS rather than relying on
-the installed copy, for example.
+Note that the high-level bindings are _separate projects_ from the
+main D-Bus package, and have their own release cycles, levels of
+maturity, and ABI stability policies. Please consult the documentation
+for your binding.
diff --git a/doc/TODO b/doc/TODO
index ace86872..7b6e1191 100644
--- a/doc/TODO
+++ b/doc/TODO
@@ -8,6 +8,8 @@ Important for 1.0
 
  - the spec should say "the protocol will not be changed incompatibly after Month DD, YYYY"
 
+ - the README documents the configure flags, should check this for being in sync with reality
+
 Important for 1.0 GLib Bindings
 ===
 
diff --git a/doc/dbus-faq.xml b/doc/dbus-faq.xml
index 47072e9e..07324049 100644
--- a/doc/dbus-faq.xml
+++ b/doc/dbus-faq.xml
@@ -7,8 +7,8 @@
 <article id="index">
   <articleinfo>
     <title>D-Bus FAQ</title>
-    <releaseinfo>Version 0.1</releaseinfo>
-    <date>22 January 2005</date>
+    <releaseinfo>Version 0.2</releaseinfo>
+    <date>07 November 2006</date>
     <authorgroup>
       <author>
 	<firstname>Havoc</firstname>
@@ -38,10 +38,14 @@
       </question>
       <answer>
         <para>
-          This is probably best answered by reading the D-Bus <ulink url="dbus-tutorial.html">tutorial</ulink>. In
+          This is probably best answered by reading the D-Bus <ulink url="dbus-tutorial.html">tutorial</ulink> or
+          the introduction to the <ulink url="dbus-specification.html">specification</ulink>. In
           short, it is a system consisting of 1) a wire protocol for exposing a
           typical object-oriented language/framework to other applications; and
           2) a bus daemon that allows applications to find and monitor one another.
+          Phrased differently, D-Bus is 1) an interprocess communication (IPC) system and 2) some higher-level 
+          structure (lifecycle tracking, service activation, security policy) provided by two bus daemons,
+          one systemwide and one per-user-session.
         </para>
       </answer>
     </qandaentry>
@@ -54,12 +58,13 @@
       </question>
       <answer>
         <para>
-          D-Bus has not yet reached 1.0. The <ulink url="README">README</ulink>
-          file has a discussion of the API/ABI stability guarantees before and
-          after 1.0. In short, there are no guarantees before 1.0, and stability
-          of both protocol and reference library will be maintained after 1.0.
-          As of January 2005 we don't expect major protocol or API changes prior
-          to the 1.0 release, but anything is possible.
+          The low-level library "libdbus" and the protocol specification are considered 
+          ABI stable. The <ulink url="README">README</ulink>
+          file has a discussion of the API/ABI stability guarantees.
+          Higher-level bindings (such as those for Qt, GLib, Python, Java, C#) each 
+          have their own release schedules and degree of maturity, not linked to 
+          the low-level library and bus daemon release. Check the project page for
+          the binding you're considering to understand that project's policies.
         </para>
       </answer>
     </qandaentry>
@@ -144,6 +149,13 @@
           are normally launched according to the bus name they will 
           have.
         </para>
+        <para>
+          People often misuse the word "service" for any 
+          bus name, but this tends to be ambiguous and confusing so is discouraged.
+          In the D-Bus docs we try to use "service" only when talking about 
+          programs the bus knows how to launch, i.e. a service always has a 
+          .service file.
+        </para>
       </answer>
     </qandaentry>
 
diff --git a/doc/dbus-specification.xml b/doc/dbus-specification.xml
index 1e4ac4f5..e1b02f38 100644
--- a/doc/dbus-specification.xml
+++ b/doc/dbus-specification.xml
@@ -7,8 +7,8 @@
 <article id="index">
   <articleinfo>
     <title>D-Bus Specification</title>
-    <releaseinfo>Version 0.11</releaseinfo>
-    <date>6 February 2005</date>
+    <releaseinfo>Version 0.12</releaseinfo>
+    <date>7 November 2006</date>
     <authorgroup>
       <author>
 	<firstname>Havoc</firstname>
@@ -114,9 +114,20 @@
       </itemizedlist>
       D-Bus is not intended to be a generic IPC system for any possible 
       application, and intentionally omits many features found in other 
-      IPC systems for this reason. D-Bus may turn out to be useful 
-      in unanticipated applications, but future versions of this 
-      spec and the reference implementation probably will not 
+      IPC systems for this reason.
+    </para>
+
+    <para>
+      At the same time, the bus daemons offer a number of features not found in
+      other IPC systems, such as single-owner "bus names" (similar to X
+      selections), on-demand startup of services, and security policies.
+      In many ways, these features are the primary motivation for developing 
+      D-Bus; other systems would have sufficed if IPC were the only goal.
+    </para>
+
+    <para>
+      D-Bus may turn out to be useful in unanticipated applications, but future
+      versions of this spec and the reference implementation probably will not
       incorporate features that interfere with the core use cases.
     </para>