Re: [PATCH] Third try at documenting command integration requirements.

From: Junio C Hamano <gitster@pobox.com>
Date: Nov 26, 2012, 20:01 UTC
Message-ID: <7vzk24qgjx.fsf@alter.siamese.dyndns.org>
In-Reply-To: <20121126053557.E56434065F@snark.thyrsus.com>

esr@thyrsus.com (Eric S. Raymond) writes:

> This document contains no new policies or proposals; it attempts
> to document established practices and interface requirements.
>
> Signed-off-by: Eric S. Raymond <esr@thyrsus.com>

I'll reword the title (readers of "git log" output 6 months down the road will not care if this is the third try or the first one) and tweak things here and there before queuing.

Show 17 quoted lines

> diff --git a/Documentation/technical/api-command.txt b/Documentation/technical/api-command.txt
> new file mode 100644
> index 0000000..c1c1afb
> --- /dev/null
> +++ b/Documentation/technical/api-command.txt
> @@ -0,0 +1,91 @@
> += Integrating new subcommands =
> +
> +This is how-to documentation for people who want to add extension
> +commands to git.  It should be read alongside api-builtin.txt.
> +
> +== Runtime environment ==
> +
> +git subcommands are standalone executables that live in the git
> +execution directory, normally /usr/lib/git-core.  The git executable itself
> +is a thin wrapper that sets GIT_DIR and passes command-line arguments
> +to the subcommand.

    $ echo >$HOME/bin/git-showenv '#!/bin/sh
    exec env'
    $ chmod +x $HOME/bin/git-showenv
    $ git showenv | grep GIT_

gives me emptyness.  I rewrote the above to:

    git subcommands are standalone executables that live in the git exec
    path, normally /usr/lib/git-core.  The git executable itself is a
    thin wrapper that knows where the subcommands live, and runs them by
    passing command-line arguments to them.

FYI, a builtin command _can_ ask the git wrapper to set up the execution environment by setting RUN_SETUP bit in its cmd_struct entry, but it is not done by default.

Show 16 quoted lines

> +== Implementation languages ==
> +
> +Most subcommands are written in C or shell.  A few are written in
> +Perl.  A tiny minority are written in Python.
> +
> +While we strongly encourage coding in portable C for portability, these
> +specific scripting languages are also acceptable. We won't accept more
> +without a very strong technical case, as we don't want to broaden the
> +git suite's required dependencies.
> +
> +Python is fine for import utilities, surgical tools, remote helpers
> +and other code at the edges of the git suite - but it should not yet
> +be used for core functions. This may change in the future; the problem
> +is that we need better Python integration in the git Windows installer
> +before we can be confident people in that environment won't
> +experience an unacceptably large loss of capability.

As Felipe and others said in the discussion, Python is not *that* special over other languages (and I think we have a Go in contrib/).

I rewrote the above to:

    Most subcommands are written in C or shell.  A few are written in
    Perl.

    While we strongly encourage coding in portable C for portability,
    these specific scripting languages are also acceptable.  We won't
    accept more without a very strong technical case, as we don't want
    to broaden the git suite's required dependencies.  Import utilities,
    surgical tools, remote helpers and other code at the edges of the
    git suite are more lenient and we allow Python (and even Tcl/tk),
    but they should not be used for core functions.

    This may change in the future.  Especially Python is not allowed in
    core because we need better Python integration in the git Windows
    installer before we can be confident people in that environment
    won't experience an unacceptably large loss of capability.

> +C commands are normally written as single modules, named after the
> +command, that link a collection of functions called libgit.  Thus,
> +your command 'git-foo' would normally be implemented as a single
> +"git-foo.c"; this organization makes it easy for people reading the

    "git-foo.c" (or "builtin/foo.c" if it is to be linked to the main
    binary);

> +4. If your command has any dependency on a a particular version of
> +your language, document it in the INSTALL file.

    s/a a/a/;

> +6. When your patch is merged, remind the maintainer to add something
> +about it in the RelNotes file.

    6. Give the maintainer a one paragraph to include in the RelNotes
    file to describe the new feature; a good place to do so is in the
    cover letter [PATCH 0/n].

Thanks.