{"thread":{"id":"32199","subject":"[PATCH] Third try at documenting command integration requirements.","startedAt":"2012-11-26T05:35:57Z","lastAt":"2012-11-28T03:36:39Z","messageCount":10,"participants":["Eric S. Raymond","Perry Hutchison","Junio C Hamano","Michael Haggerty"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"203857","messageId":"20121126053557.E56434065F@snark.thyrsus.com","threadId":"32199","inReplyTo":null,"subject":"[PATCH] Third try at documenting command integration requirements.","fromName":"Eric S. Raymond","fromEmail":"esr@thyrsus.com","sentAt":"2012-11-26T05:35:57Z","receivedAt":"2012-11-26T05:35:57Z","isPatch":true,"sender":{"key":"esr@thyrsus.com","avatar":"https://avatars.githubusercontent.com/u/727961?v=4"},"body":"This document contains no new policies or proposals; it attempts\nto document established practices and interface requirements.\n\nSigned-off-by: Eric S. Raymond \n---\n Documentation/technical/api-command.txt | 91 +++++++++++++++++++++++++++++++\n 1 file changed, 91 insertions(+)\n create mode 100644 Documentation/technical/api-command.txt\n\ndiff --git a/Documentation/technical/api-command.txt b/Documentation/technical/api-command.txt\nnew file mode 100644\nindex 0000000..c1c1afb\n--- /dev/null\n+++ b/Documentation/technical/api-command.txt\n@@ -0,0 +1,91 @@\n+= Integrating new subcommands =\n+\n+This is how-to documentation for people who want to add extension\n+commands to git. It should be read alongside api-builtin.txt.\n+\n+== Runtime environment ==\n+\n+git subcommands are standalone executables that live in the git\n+execution directory, normally /usr/lib/git-core. The git executable itself\n+is a thin wrapper that sets GIT_DIR and passes command-line arguments\n+to the subcommand.\n+\n+(If \"git foo\" is not found in the git exec path, the wrapper\n+will look in the rest of your $PATH for it. Thus, it's possible\n+to write local git extensions that don't live in system space.)\n+\n+== Implementation languages ==\n+\n+Most subcommands are written in C or shell. A few are written in\n+Perl. A tiny minority are written in Python.\n+\n+While we strongly encourage coding in portable C for portability, these\n+specific scripting languages are also acceptable. We won't accept more\n+without a very strong technical case, as we don't want to broaden the\n+git suite's required dependencies.\n+\n+Python is fine for import utilities, surgical tools, remote helpers\n+and other code at the edges of the git suite - but it should not yet\n+be used for core functions. This may change in the future; the problem\n+is that we need better Python integration in the git Windows installer\n+before we can be confident people in that environment won't\n+experience an unacceptably large loss of capability.\n+\n+C commands are normally written as single modules, named after the\n+command, that link a collection of functions called libgit. Thus,\n+your command 'git-foo' would normally be implemented as a single\n+\"git-foo.c\"; this organization makes it easy for people reading the\n+code to find things.\n+\n+See the CodingGuidelines document for other guidance on what we consider\n+good practice in C and shell, and api-builtin.txt for the support\n+functions available to built-in commands written in C.\n+\n+== What every extension command needs ==\n+\n+You must have a man page, written in asciidoc (this is what git help\n+followed by your subcommand name will display). Be aware that there is\n+a local asciidoc configuration and macros which you should use. It's\n+often helpful to start by cloning an existing page and replacing the\n+text content.\n+\n+You must have a test, written to report in TAP (Test Anything Protocol).\n+Tests are executables (usually shell scripts) that live in the 't' \n+subdirectory of the tree. Each test name begins with 't' and a sequence\n+number that controls where in the test sequence it will be executed;\n+conventionally the rest of the name stem is that of the command \n+being tested.\n+\n+Read the file t/README to learn more about the conventions to be used\n+in writing tests, and the test support library.\n+\n+== Integrating a command ==\n+\n+Here are the things you need to do when you want to merge a new \n+subcommand into the git tree.\n+\n+0. Don't forget to sign off your patch!\n+\n+1. Append your command name to one of the variables BUILTIN_OBJS,\n+EXTRA_PROGRAMS, SCRIPT_SH, SCRIPT_PERL or SCRIPT_PYTHON.\n+\n+2. Drop its test in the t directory.\n+\n+3. If your command is implemented in an interpreted language with a \n+p-code intermediate form, make sure .gitignore in the main directory\n+includes a pattern entry that ignores such files. Python .pyc and\n+.pyo files will already be covered.\n+\n+4. If your command has any dependency on a a particular version of\n+your language, document it in the INSTALL file.\n+\n+5. There is a file command-list.txt in the distribution main directory\n+that categorizes commands by type, so they can be listed in appropriate\n+subsections in the documentation's summary command list. Add an entry \n+for yours. To understand the categories, look at git-cmmands.txt\n+in the main directory.\n+\n+6. When your patch is merged, remind the maintainer to add something\n+about it in the RelNotes file.\n+\n+That's all there is to it.\n-- \n1.7.9.5\n\n-- \n\t\tEric S. Raymond\n\nWhether the authorities be invaders or merely local tyrants, the\neffect of such [gun control] laws is to place the individual at the \nmercy of the state, unable to resist.\n -- Robert Anson Heinlein, 1949\n"},{"id":"203860","messageId":"50b31528.daN7oo8Yh6Jzvx5V%perryh@pluto.rain.com","threadId":"32199","inReplyTo":"20121126053557.E56434065F@snark.thyrsus.com","subject":"Re: [PATCH] Third try at documenting command integration requirements.","fromName":"Perry Hutchison","fromEmail":"perryh@pluto.rain.com","sentAt":"2012-11-26T08:07:20Z","receivedAt":"2012-11-26T08:07:20Z","isPatch":true,"sender":{"key":"perryh@pluto.rain.com","avatar":null},"body":"esr@thyrsus.com (Eric S. Raymond) wrote:\n\n> This document contains no new policies or proposals; it attempts\n> to document established practices and interface requirements.\n...\n> +4. If your command has any dependency on a a particular version of\n ^^^\n\ntypo. (granted this is an extreme nit)\n"},{"id":"203911","messageId":"7vzk24qgjx.fsf@alter.siamese.dyndns.org","threadId":"32199","inReplyTo":"20121126053557.E56434065F@snark.thyrsus.com","subject":"Re: [PATCH] Third try at documenting command integration requirements.","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2012-11-26T20:01:54Z","receivedAt":"2012-11-26T20:01:54Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"esr@thyrsus.com (Eric S. Raymond) writes:\n\n> This document contains no new policies or proposals; it attempts\n> to document established practices and interface requirements.\n>\n> Signed-off-by: Eric S. Raymond \n\nI'll reword the title (readers of \"git log\" output 6 months down the\nroad will not care if this is the third try or the first one) and\ntweak things here and there before queuing.\n\n> diff --git a/Documentation/technical/api-command.txt b/Documentation/technical/api-command.txt\n> new file mode 100644\n> index 0000000..c1c1afb\n> --- /dev/null\n> +++ b/Documentation/technical/api-command.txt\n> @@ -0,0 +1,91 @@\n> += Integrating new subcommands =\n> +\n> +This is how-to documentation for people who want to add extension\n> +commands to git. It should be read alongside api-builtin.txt.\n> +\n> +== Runtime environment ==\n> +\n> +git subcommands are standalone executables that live in the git\n> +execution directory, normally /usr/lib/git-core. The git executable itself\n> +is a thin wrapper that sets GIT_DIR and passes command-line arguments\n> +to the subcommand.\n\n $ echo >$HOME/bin/git-showenv '#!/bin/sh\n exec env'\n $ chmod +x $HOME/bin/git-showenv\n $ git showenv | grep GIT_\n\ngives me emptyness. I rewrote the above to:\n\n git subcommands are standalone executables that live in the git exec\n path, normally /usr/lib/git-core. The git executable itself is a\n thin wrapper that knows where the subcommands live, and runs them by\n passing command-line arguments to them.\n\nFYI, a builtin command _can_ ask the git wrapper to set up the\nexecution environment by setting RUN_SETUP bit in its cmd_struct\nentry, but it is not done by default.\n\n> +== Implementation languages ==\n> +\n> +Most subcommands are written in C or shell. A few are written in\n> +Perl. A tiny minority are written in Python.\n> +\n> +While we strongly encourage coding in portable C for portability, these\n> +specific scripting languages are also acceptable. We won't accept more\n> +without a very strong technical case, as we don't want to broaden the\n> +git suite's required dependencies.\n> +\n> +Python is fine for import utilities, surgical tools, remote helpers\n> +and other code at the edges of the git suite - but it should not yet\n> +be used for core functions. This may change in the future; the problem\n> +is that we need better Python integration in the git Windows installer\n> +before we can be confident people in that environment won't\n> +experience an unacceptably large loss of capability.\n\nAs Felipe and others said in the discussion, Python is not *that*\nspecial over other languages (and I think we have a Go in contrib/).\n\nI rewrote the above to:\n\n Most subcommands are written in C or shell. A few are written in\n Perl.\n\n While we strongly encourage coding in portable C for portability,\n these specific scripting languages are also acceptable. We won't\n accept more without a very strong technical case, as we don't want\n to broaden the git suite's required dependencies. Import utilities,\n surgical tools, remote helpers and other code at the edges of the\n git suite are more lenient and we allow Python (and even Tcl/tk),\n but they should not be used for core functions.\n\n This may change in the future. Especially Python is not allowed in\n core because we need better Python integration in the git Windows\n installer before we can be confident people in that environment\n won't experience an unacceptably large loss of capability.\n\n> +C commands are normally written as single modules, named after the\n> +command, that link a collection of functions called libgit. Thus,\n> +your command 'git-foo' would normally be implemented as a single\n> +\"git-foo.c\"; this organization makes it easy for people reading the\n\n \"git-foo.c\" (or \"builtin/foo.c\" if it is to be linked to the main\n binary);\n\n> +4. If your command has any dependency on a a particular version of\n> +your language, document it in the INSTALL file.\n\n s/a a/a/;\n\n> +6. When your patch is merged, remind the maintainer to add something\n> +about it in the RelNotes file.\n\n 6. Give the maintainer a one paragraph to include in the RelNotes\n file to describe the new feature; a good place to do so is in the\n cover letter [PATCH 0/n].\n\nThanks.\n"},{"id":"203936","messageId":"20121126214134.GA1713@thyrsus.com","threadId":"32199","inReplyTo":"7vzk24qgjx.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH] Third try at documenting command integration requirements.","fromName":"Eric S. Raymond","fromEmail":"esr@thyrsus.com","sentAt":"2012-11-26T21:41:34Z","receivedAt":"2012-11-26T21:41:34Z","isPatch":true,"sender":{"key":"esr@thyrsus.com","avatar":"https://avatars.githubusercontent.com/u/727961?v=4"},"body":"Junio C Hamano :\n> I'll reword the title (readers of \"git log\" output 6 months down the\n> road will not care if this is the third try or the first one) and\n> tweak things here and there before queuing.\n\nResult looks good from here.\n \nThe next things on my git to-do list are \n\n1. Audit the in-tree Python for version dependencies. Add floor-version checks.\n\n2. Submit a doc patch containing guidelines that (a) Python scripts should\n check for their floor version and error out gracefully if they won't\n run with the host's interpreter, and (b) Python scripts sbould be\n 2.6-compatible.\n\n3. Submit the git-weave integration patch. I could do that now, but while my\n regression test speaks TAP it doesn't presently use the test library. I plan\n to re-work it to do that.\n\nDo you have any other pending tasks for which you think my expertise would\nbe useful? I refer specifically to the facts that (a) I find writing and \nediting documentation easy and can do it rapidly, (b) I'm a Python expert, \nand (c) I am very interested in, and know a lot about, tools for repository\nsurgery and import/export.\n-- \n\t\tEric S. Raymond\n"},{"id":"203937","messageId":"7v624sqbxo.fsf@alter.siamese.dyndns.org","threadId":"32199","inReplyTo":"20121126053557.E56434065F@snark.thyrsus.com","subject":"Re: [PATCH] Third try at documenting command integration requirements.","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2012-11-26T21:41:39Z","receivedAt":"2012-11-26T21:41:39Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"esr@thyrsus.com (Eric S. Raymond) writes:\n\n> @@ -0,0 +1,91 @@\n> += Integrating new subcommands =\n> +\n> +This is how-to documentation for people who want to add extension\n> +commands to git. It should be read alongside api-builtin.txt.\n> +\n> +== Runtime environment ==\n> +\n> +git subcommands are standalone executables that live in the git\n\nEven though \"={n} title ={n}\" is a valid AsciiDoc heading, all other\nfiles use (older) underscored titles; please refrain from being\noriginal.\n\nEspecially, this interferes with the way the api-index.txt file in\nthe same directory is autogenerated.\n"},{"id":"203941","messageId":"20121126220150.GC1713@thyrsus.com","threadId":"32199","inReplyTo":"7v624sqbxo.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH] Third try at documenting command integration requirements.","fromName":"Eric S. Raymond","fromEmail":"esr@thyrsus.com","sentAt":"2012-11-26T22:01:50Z","receivedAt":"2012-11-26T22:01:50Z","isPatch":true,"sender":{"key":"esr@thyrsus.com","avatar":"https://avatars.githubusercontent.com/u/727961?v=4"},"body":"Junio C Hamano :\n> Even though \"={n} title ={n}\" is a valid AsciiDoc heading, all other\n> files use (older) underscored titles; please refrain from being\n> original.\n> \n> Especially, this interferes with the way the api-index.txt file in\n> the same directory is autogenerated.\n\nNoted for the future, thank you.\n-- \n\t\tEric S. Raymond\n"},{"id":"203988","messageId":"50B4A8E1.7050801@alum.mit.edu","threadId":"32199","inReplyTo":"20121126214134.GA1713@thyrsus.com","subject":"Re: [PATCH] Third try at documenting command integration requirements.","fromName":"Michael Haggerty","fromEmail":"mhagger@alum.mit.edu","sentAt":"2012-11-27T11:49:53Z","receivedAt":"2012-11-27T11:49:53Z","isPatch":true,"sender":{"key":"mhagger@alum.mit.edu","avatar":"https://avatars.githubusercontent.com/u/119718?v=4"},"body":"On 11/26/2012 10:41 PM, Eric S. Raymond wrote:\n> The next things on my git to-do list are \n> [...]\n> 2. Submit a doc patch containing guidelines that (a) Python scripts should\n> check for their floor version and error out gracefully if they won't\n> run with the host's interpreter, and (b) Python scripts sbould be\n> 2.6-compatible.\n\nOK, now let's discuss *which* minimum Python version that git should\nsupport in the hypothetical new world...\n\nData point: Mercurial supports Python 2.4 - 2.7 with the following\nexplanation [1]:\n\n We will continue to support Python 2.4 as long as it doesn't\n present a significant barrier to development. Given that Python 2.5\n and later don't contain any features that we're dying to use, that\n may be a long time off. [...]\n\n We also will continue to support Python 2.x as long as there is a\n significant installed base in the form of Red Hat Enterprise Linux\n and Ubuntu LTS users. RHEL 5, which uses Python 2.4, will reach the\n end of the \"production 2\" portion of its lifecycle in Q1 2014 and\n the end of its regular lifecycle in 2017.\n\nIt would be a shame to leave RHEL 5 users behind if Python is used to\nimplement important git functionality. Python 2.4 is missing some of\nPython's shiny new features, but still quite OK. What features would\nyou miss the most if we were to target Python 2.4 instead of 2.6?\n\nMichael\n\n[1] http://mercurial.selenic.com/wiki/SupportedPythonVersions\n\n-- \nMichael Haggerty\nmhagger@alum.mit.edu\nhttp://softwareswirl.blogspot.com/\n"},{"id":"204010","messageId":"20121127175618.GA11845@thyrsus.com","threadId":"32199","inReplyTo":"50B4A8E1.7050801@alum.mit.edu","subject":"Re: [PATCH] Third try at documenting command integration requirements.","fromName":"Eric S. Raymond","fromEmail":"esr@thyrsus.com","sentAt":"2012-11-27T17:56:19Z","receivedAt":"2012-11-27T17:56:19Z","isPatch":true,"sender":{"key":"esr@thyrsus.com","avatar":"https://avatars.githubusercontent.com/u/727961?v=4"},"body":"Michael Haggerty :\n> OK, now let's discuss *which* minimum Python version that git should\n> support in the hypothetical new world...\n\nBy all means!\n \n> It would be a shame to leave RHEL 5 users behind if Python is used to\n> implement important git functionality. Python 2.4 is missing some of\n> Python's shiny new features, but still quite OK. What features would\n> you miss the most if we were to target Python 2.4 instead of 2.6?\n\nOff the top of my head...the 'with' statement, the conditional\nexpression, and built-in JSON support. Other developers would be\nlikely to kick about the string format() method; personally I'm\ncheerfully old-school about that.\n\nI agree that 2.4 is still quite OK. I'm a little concerned that dropping that\nfar back might store up some transition problems for the day we decide to\nmake the jump to Python 3.\n\nOn the other hand, I think gating features on RHEL5 might be\nexcessively cautious. According to [1], RHEL will red-zone within 30\ndays if it hasn't done so already ([1] says \"Q4\"). And RHEL6 (with\nPython 2.6) has been shipping for two years.\n\nPolicy suggestion: we aim to stay friendly for every version of RHEL that\nis still in Support 1. I doubt anyone will code anything critical \nin Python before Dec 31st - I'm certainly not planning to!\n\n[1] http://en.wikipedia.org/wiki/Red_Hat_Enterprise_Linux RHEL5 is going\n-- \n\t\tEric S. Raymond\n"},{"id":"204095","messageId":"7vobiijxol.fsf@alter.siamese.dyndns.org","threadId":"32199","inReplyTo":"20121127175618.GA11845@thyrsus.com","subject":"Re: [PATCH] Third try at documenting command integration requirements.","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2012-11-28T01:58:18Z","receivedAt":"2012-11-28T01:58:18Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Eric S. Raymond\" writes:\n\n> I agree that 2.4 is still quite OK. I'm a little concerned that dropping that\n> far back might store up some transition problems for the day we decide to\n> make the jump to Python 3.\n>\n> On the other hand, I think gating features on RHEL5 might be\n> excessively cautious. According to [1], RHEL will red-zone within 30\n> days if it hasn't done so already ([1] says \"Q4\"). And RHEL6 (with\n> Python 2.6) has been shipping for two years.\n\nI won't worry about Python 3 yet; in what timeframe did Python's\ni18n/unicode support become usable? In 2.4, or 2.6?\n"},{"id":"204122","messageId":"20121128033639.GC1669@thyrsus.com","threadId":"32199","inReplyTo":"7vobiijxol.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH] Third try at documenting command integration requirements.","fromName":"Eric S. Raymond","fromEmail":"esr@thyrsus.com","sentAt":"2012-11-28T03:36:39Z","receivedAt":"2012-11-28T03:36:39Z","isPatch":true,"sender":{"key":"esr@thyrsus.com","avatar":"https://avatars.githubusercontent.com/u/727961?v=4"},"body":"Junio C Hamano :\n> I won't worry about Python 3 yet; in what timeframe did Python's\n> i18n/unicode support become usable? In 2.4, or 2.6?\n\nEr, it depends on what you consider \"usable\".\n\nUnicode integration turned out to have a lot messier edge cases than\nanyone understood going in. First-cut support was in 1.6, but I'd say\nit still has some pretty sharp edges *today*. Which is why 3.0 has\ngone all-Unicode-all-the-time. The problems mostly come from having\ntwo different notions of \"string\" that don't really mix well.\n\nMe, I still avoid the hell out of Unicode in Python. And occasionally\nfund myself cursing a library maintainer who didn't.\n-- \n\t\tEric S. Raymond\n"}]}