[RFC/PATCH] Git.pm: discourage casual use

From: Jonathan Nieder <jrnieder@gmail.com>
Date: Dec 2, 2010, 19:05 UTC
Message-ID: <20101202190546.GI3962@burratino>
In-Reply-To: <AANLkTimKKssBbtuLKCqG9WGbOe+-CH4pc5PDaNxCH_PS@mail.gmail.com>

Git's internal perl interface still does not have a stable API, and meanwhile CPAN has a number of modules to fulfill the need for a perl git interface. The line

	# Totally unstable API.
	$VERSION = '0.01';

in the source makes this clear enough, but users who just looked at git-svn.perl and then tried "perldoc Git" would not notice. Add a note to the manual to warn the reader.

Inspired-by: Yves Orton <demerphq@gmail.com>
Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
---
demerphq wrote:

Show 7 quoted lines

> And well the line:
> 
> # Totally unstable API.
> $VERSION = '0.01';
> 
> STRONGLY suggests that the module should not be used by code outside
> the Git package itself.

So how about something like this patch, to start?

diff --git a/perl/Git.pm b/perl/Git.pm
index 6cb0dd1..7f6c500 100644
--- a/perl/Git.pm
+++ b/perl/Git.pm
@@ -63,12 +63,16 @@ require Exporter;
 
 =head1 DESCRIPTION
 
-This module provides Perl scripts easy way to interface the Git version control
-system. The modules have an easy and well-tested way to call arbitrary Git
+This module provides an easy way to interact with the Git version control
+system for Git's internal perl scripts.
+The modules have an easy and well-tested way to call arbitrary Git
 commands; in the future, the interface will also provide specialized methods
 for doing easily operations which are not totally trivial to do over
 the generic command interface.
 
+Note: this module should not be used by code outside the Git package itself,
+since the API is not stable yet.
+
 While some commands can be executed outside of any context (e.g. 'version'
 or 'init'), most operations require a repository context, which in practice
 means getting an instance of the Git object using the repository() constructor.