[PATCH] Add documentation on how to integrate commands.

[PATCH] Add documentation on how to integrate commands.

[Eric S. Raymond]

---
 Documentation/CommandIntegration |   69 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 69 insertions(+)
 create mode 100644 Documentation/CommandIntegration

diff --git a/Documentation/CommandIntegration b/Documentation/CommandIntegration
new file mode 100644
index 0000000..be248f7
--- /dev/null
+++ b/Documentation/CommandIntegration
@@ -0,0 +1,69 @@
+= Integrating new subcommands =
+
+This is how-to documentation for people who want to add extension
+commands to git.
+
+== 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.
+
+(If "git foo" is not found in the git execution directory, the wrapper
+will look in the rest of your $PATH for it.  Thus, it's possible
+to write local git extensions that don't live in system space.)
+
+== 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.
+
+C commands are normally written as single modules, named after the
+command, that link a core library 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 code to find things.
+
+See the CodingGuidelines document for other guidance on what we consider
+good practice in C and shell.
+
+== What every extension command needs ==
+
+You must have a man page, written in asciidoc (this is what git help
+followed by your subcommand name will display).  Be aware that there is
+a local asciidoc configuration and macros which you should use.  It's
+often helpful to start by cloning an existing page and replacing the
+text content.
+
+You must have a test, written to report in TAP (Test Anything Protocol).
+Tests are executables (usually shell scripts) that live in the 't' 
+subdirectory of the tree.  Each test name begins with 't' and a sequence
+number that controls where in the test sequence it will be executed;
+conventionally the rest of the name stem is that of the command 
+being tested.
+
+If your test requires an example repository, create it yourself in the
+test script.  There is a test library of shell functions that assists
+wit this; when you use it, the environment is set in a predictable way
+so the author, committer and timestamps are all set to a single well
+known value, allowing git to create a commit that is reproducible on
+all platforms. A test_tick function is used in the scripts to move the
+clock, allowing different times to be used. For an example see
+t7502-commit.sh, or really any script in that directory.
+
+== Integrating a command ==
+
+Here are the things you need to do when you want to merge a new 
+subcommand into the git tree.
+
+1. Append your command name to one of the variables BUILTIN_OBJS,
+EXTRA_PROGRAMS, SCRIPT_SH, SCRIPT_PERL or SCRIPT_PYTHON.
+
+2. Drop its test in the t directory.
+
+That's all there is to it.
-- 
1.7.9.5



-- 
		<a href="http://www.catb.org/~esr/">Eric S. Raymond</a>

The same applies for other kinds of long-lasting low-level pain. [...]
The body's response to being jabbed, pierced, and cut is to produce
endorphins. [...]  So here's my programme for breaking that cycle of
dependency on Windows: get left arm tattooed with dragon motif, buy a
crate of Jamaican Hot! Pepper Sauce, get nipples pierced.  With any
luck that will produce enough endorphins to make Windows completely
redundant, and I can then upgrade to Linux and get on with things.
	-- Pieter Hintjens

Re: [PATCH] Add documentation on how to integrate commands.

[Pete Wyckoff]

esr@thyrsus.com wrote on Sat, 24 Nov 2012 07:23 -0500:
> +== Integrating a command ==
> +
> +Here are the things you need to do when you want to merge a new 
> +subcommand into the git tree.
> +
> +1. Append your command name to one of the variables BUILTIN_OBJS,
> +EXTRA_PROGRAMS, SCRIPT_SH, SCRIPT_PERL or SCRIPT_PYTHON.
> +
> +2. Drop its test in the t directory.
> +
> +That's all there is to it.

Nice start.  A few other details; I recently did this for git-p4
(python).

.gitignore: ignore the auto-generated script, e.g. when
git-foo.py is built into git-foo.

INSTALL: note language requirements if odd (see python section)

command-list.txt: categorization of commands for git(1) etc.

RelNotes: Junio generally does this.


Also please read Documentation/technical/api-builtin.txt to
see how to add a built-in command.  It also has comments that
are identical for both built-in and stand-alone command.  Could
be that your text would better go near or with that one, as perhaps
api-command.txt.

		-- Pete

Re: [PATCH] Add documentation on how to integrate commands.

[Eric S. Raymond]

Pete Wyckoff <pw@padd.com>:
> Nice start.  A few other details; I recently did this for git-p4
> (python).
> 
> .gitignore: ignore the auto-generated script, e.g. when
> git-foo.py is built into git-foo.
> 
> INSTALL: note language requirements if odd (see python section)
> 
> command-list.txt: categorization of commands for git(1) etc.
> 
> RelNotes: Junio generally does this.
> 
> 
> Also please read Documentation/technical/api-builtin.txt to
> see how to add a built-in command.  It also has comments that
> are identical for both built-in and stand-alone command.  Could
> be that your text would better go near or with that one, as perhaps
> api-command.txt.

Good points.  I will submit a revised patch later today.
-- 
		<a href="http://www.catb.org/~esr/">Eric S. Raymond</a>

Re: [PATCH] Add documentation on how to integrate commands.

[Eric S. Raymond]

Working on my revised patch...

Pete Wyckoff <pw@padd.com>:
> Nice start.  A few other details; I recently did this for git-p4
> (python).
> 
> .gitignore: ignore the auto-generated script, e.g. when
> git-foo.py is built into git-foo.

Added:

    3. If your command is implemented in an interpreted language with a 
    p-code intermediate form, make sure .gitignore in the main directory
    includes a pattern entry that ignores such files.  Python .pyc and
    .pyo files will already be covered.

> INSTALL: note language requirements if odd (see python section)

Added:

    4. If your command has dependency on a particular version, document
    it in the INSTALL file.
 
> command-list.txt: categorization of commands for git(1) etc.

Are the values in the right-hand column documented somewhere?  What
uses them, and for what purposes.
 
> RelNotes: Junio generally does this.

Added:

    6. When your patch is merged, remind the maintainer to add something
    about it in the RelNotes file.
 
> Also please read Documentation/technical/api-builtin.txt to
> see how to add a built-in command.  It also has comments that
> are identical for both built-in and stand-alone command.  Could
> be that your text would better go near or with that one, as perhaps
> api-command.txt.

I think this is a good suggestion and will implement it.

If someone can explain the values used in command-list.txt, or (better) point
me to documentation of them, that will enable me to finish the revised patch.
-- 
		<a href="http://www.catb.org/~esr/">Eric S. Raymond</a>

Re: [PATCH] Add documentation on how to integrate commands.

[Michael Haggerty]

On 11/24/2012 01:23 PM, Eric S. Raymond wrote:
> ---
>  Documentation/CommandIntegration |   69 ++++++++++++++++++++++++++++++++++++++
>  1 file changed, 69 insertions(+)
>  create mode 100644 Documentation/CommandIntegration
> 
> diff --git a/Documentation/CommandIntegration b/Documentation/CommandIntegration
> new file mode 100644
> index 0000000..be248f7
> --- /dev/null
> +++ b/Documentation/CommandIntegration
> @@ -0,0 +1,69 @@
> [...]
> +You must have a test, written to report in TAP (Test Anything Protocol).
> +Tests are executables (usually shell scripts) that live in the 't' 
> +subdirectory of the tree.  Each test name begins with 't' and a sequence
> +number that controls where in the test sequence it will be executed;
> +conventionally the rest of the name stem is that of the command 
> +being tested.
> +
> +If your test requires an example repository, create it yourself in the
> +test script.  There is a test library of shell functions that assists
> +wit this; when you use it, the environment is set in a predictable way
> +so the author, committer and timestamps are all set to a single well
> +known value, allowing git to create a commit that is reproducible on
> +all platforms. A test_tick function is used in the scripts to move the
> +clock, allowing different times to be used. For an example see
> +t7502-commit.sh, or really any script in that directory.

I think that here a reference to the file t/README would help (and
perhaps make part of your text redundant).

Michael

-- 
Michael Haggerty
mhagger@alum.mit.edu
http://softwareswirl.blogspot.com/

Re: [PATCH] Add documentation on how to integrate commands.

[Eric S. Raymond]

Michael Haggerty <mhagger@alum.mit.edu>:
> I think that here a reference to the file t/README would help (and
> perhaps make part of your text redundant).

Thank you, done.
-- 
		<a href="http://www.catb.org/~esr/">Eric S. Raymond</a>

Re: [PATCH] Add documentation on how to integrate commands.

[Junio C Hamano]

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

> ---

Sign off?

>  Documentation/CommandIntegration |   69 ++++++++++++++++++++++++++++++++++++++
>  1 file changed, 69 insertions(+)
>  create mode 100644 Documentation/CommandIntegration
>
> diff --git a/Documentation/CommandIntegration b/Documentation/CommandIntegration
> new file mode 100644
> index 0000000..be248f7
> --- /dev/null
> +++ b/Documentation/CommandIntegration
> @@ -0,0 +1,69 @@
> += Integrating new subcommands =
> +
> +This is how-to documentation for people who want to add extension
> +commands to git.
> +
> +== 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.
> +
> +(If "git foo" is not found in the git execution directory, the wrapper
> +will look in the rest of your $PATH for it.  Thus, it's possible

As the first sentence in this paragraph does not make it clear
enough that you are defining a new term "git execution directory",
"execution directory" here may be misleading and can easily be
mistaken as if we look something in the directory where the user
runs "git" in.  We usually call it "exec path".

> +== 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.

Actually, we tend to avoid Python dependency for anything important
and allow it only on fringes; people who lack Python environment are
not missing much, and we would want to keep it that way until the
situation on the Windows front changes.

> +C commands are normally written as single modules, named after the
> +command, that link a core library called libgit.  Thus, your command

I would prefer to see this sentence not call libgit.a a "library".
We primarily use libgit.a to let linker pick necessary object files
without us having to list object files for non-builtin command
implementations and it is not designed to be used by other people.

> +== Integrating a command ==
> +
> +Here are the things you need to do when you want to merge a new 
> +subcommand into the git tree.
> +
> +1. Append your command name to one of the variables BUILTIN_OBJS,
> +EXTRA_PROGRAMS, SCRIPT_SH, SCRIPT_PERL or SCRIPT_PYTHON.
> +
> +2. Drop its test in the t directory.
> +
> +That's all there is to it.

And when sending a patch in, do not forget to sign off your patches
;-)

Re: [PATCH] Add documentation on how to integrate commands.

[Eric S. Raymond]

Junio C Hamano <gitster@pobox.com>:
> As the first sentence in this paragraph does not make it clear
> enough that you are defining a new term "git execution directory",
> "execution directory" here may be misleading and can easily be
> mistaken as if we look something in the directory where the user
> runs "git" in.  We usually call it "exec path".

Fixed.

> Actually, we tend to avoid Python dependency for anything important
> and allow it only on fringes; people who lack Python environment are
> not missing much, and we would want to keep it that way until the
> situation on the Windows front changes.

Added:

    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.

I will also take this as a part-resolution of the related policy thread. 
Issue perhaps to be revisited when the Windows port gets the Python support
to a good state.

I will submit for separate consideration a patch proposing the following
new guidelines:

1. Python code SHOULD NOT require an interpreter version newer than 2.6.

2. Python code SHOULD check the interpreter version and exit gracefully
   with an explanation if it detects that its dependency cannot be satisfied.

> I would prefer to see this sentence not call libgit.a a "library".
> We primarily use libgit.a to let linker pick necessary object files
> without us having to list object files for non-builtin command
> implementations and it is not designed to be used by other people.

Fixed.  I now refer to it as a "collection of functions".

> And when sending a patch in, do not forget to sign off your patches
> ;-)

Added.  I will submit a third time with a signoff. :-)
-- 
		<a href="http://www.catb.org/~esr/">Eric S. Raymond</a>