Contrib

[Mads Kiilerich]

Revisiting an old thread I haven't given up on ...

Was Re: [PATCH] mercurial.spec: Install mq.el, hgk requires tk, 
uncompressed man pages

Matt Mackall wrote, On 01/06/2010 06:05 AM:
> On Wed, 2010-01-06 at 03:01 +0100, Mads Kiilerich wrote:
>    
>> I don't understand what the contrib folder is for. Is it unsupported or
>> undocumented? Broken stuff? The place where all contributions go? Or
>> just a place where random things are dumped and forgotten? I don't think
>> anybody would benefit from just including the whole contrib folder as-is
>> in the installer/package.
>>      
> It is unsupported and largely undocumented, and yes, some things in
> there are broken. But most of it is potentially useful.

I fail to understand how that situation can be appreciated.

Contrib contains stuff which is an essential part of Mercurials 
offering, and people expect it to work. Installers and binary packages 
have to include parts from contrib, but taking unsupported and largely 
undocumented stuff and mixing it with the good stuff and pretend that 
all of it is supported is not a good solution.

Much of the content in contrib do have a quality similar to the rest of 
Mercurial - and if it is of lower quality then it is often because it 
lives for itself and doesn't get the attention it deserves. It doesn't 
pop up when searching or browsing the code, it isn't integrated in the 
test suite (except for dumprevlog and simplemerge), and there is no 
expectation that contrib is maintained like all the other code. The name 
"contrib" hints that it is a "somebody else's problem field". It seems 
like a mess where nobody has any obligation to clean up.

Years ago it kind of made sense to include incomplete or experimental 
code temporarily in contrib, but now there are so many places small 
projects can be hosted that that probably is a better solution in some 
cases.

I suggest and ask that we make it a long-term goal to make contrib go 
away, by making its parts either fully supported and documented (and 
moved somewhere else) or removed.

I understand that something might be impossible to change because they 
are widely used and relied on. That indicates that it to some extent is 
supported, and also points out how important it is that these parts get 
proper support and a good stable location.


A quick analysis of what currently can be found in contrib and what 
could happen:

CONFIGURATION - installers can install to /etc/mercurial/hgrc.d/*.rc:
mergetools.hgrc # rename to .rc
sample.hgrc # rename to .rc

LIBEXEC - executables, but not necessarily in users PATH, move to bin or 
libexec folder:
# usable user commands
hgdiff
simplemerge
convert-repo # usage? replaced by extension? remove it!
# server commands
hgwebdir.fcgi
hgwebdir.wsgi
hg-ssh
hgsh # still used and maintained? drop!
# advanced tools
dumprevlog # +x
undumprevlog # +x
rewrite-log
shrink-revlog.py # remove .py file extension
# extension helper
hgk # must be in path or referenced by hgk.path (but should probably be 
deprecated now)
git-viz # dead? remove it!
tmplrewrite.py # usage? outdated! remove it!

EXTENSIONS - put them in hgext, perhaps give them a debug-prefix and 
hide them from the extension list:
memory.py
perf.py

INTEGRATION - binary packages should include and install these when and 
where appropriate:
bash_completion
tcsh_completion
tcsh_completion_build.sh
zsh_completion
mercurial.el
mq.el
vim # getting upstreamed

DOCS:
logo-droplets.svg # move to doc folder
python-hook-examples.py # move to wiki
xml.rnc # move to doc folder (or to mercurial/templates right next to 
map-cmdline.xml and template-vars.txt)

INSTALLERS - meta content and scripts - move to installers or build folder:
buildrpm
mercurial.spec # -x
macosx/Readme.html
macosx/Welcome.html
macosx/macosx-build.txt
win32/ReadMe.html
win32/hg.bat
win32/mercurial.ico
win32/mercurial.ini
win32/mercurial.iss
win32/postinstall.txt
win32/win32-build.txt


/Mads