Re: [RFC] gitweb wishlist and TODO list

[Jakub Narebski <jnareb@gmail.com>]

On Thu, 25 Sep 2008, Wincent Colaiuta wrote:
> El 25/9/2008, a las 12:30, Jakub Narebski escribió:
> 
> > This is yet another series of planned gitweb features. It expands more
> > on new user-visible features than on improving gitweb code (therefore
> > for example using Git.pm/Git::Repo, gitweb caching, and list form of
> > open for pipelines are not mentioned here).
> >
> > Which tasks / features are most requested?  Which tasks should be done
> > first?  What do you have on your gitweb TODO list?
> 
> One which I'm looking at doing is supporting reading the "README.html"  
> from the tree indicated by the current HEAD instead of reading it from  
> a file in the .git directory.

One problem is with the concept of using "current HEAD" for that.

I have nothing against for example showing README or README.html (in
some order of preference), or initial fragment of it with link to full
version ('blob' view), either below or above 'tree' view, like
GitHub and Gitorious does.  When you are on 'tree' view you are on
some branch, even implicitly[1].  But for 'summary' view, which is
currently the only view that shows $GIT_DIR/README.html, you are not.

It might happen that you push to git hosting site while on some side
unrelated branch like 'todo', 'html' or 'man' pages in git.git, or
are on branch spawned off subtree-merged subproject like git-gui;
or your gitweb shows state of live non-bare repo and you happen to be
on such branch.  What then?  Repository description vanishing by
accident is not a good solution...


[1] And you can have different READMEs shown for different subprojects,
like there is README, and gitweb/README, and contrib/README, etc.
 
> This should make tracking and updating such READMEs a little easier as  
> all that'll be required is a "push" to advance the HEAD and the new  
> README goes live.
> 
> Obviously, will have to make this optional and configurable. I'm  
> thinking of providing a means of specifying the filename to look for  
> (no filename, the default, means don't look), and also a setting to  
> indicate the content type of the file (either plain text, which would  
> be wrapped in a <pre></pre> block with HTML entities used where  
> appropriate, or HTML which would be included verbatim).

Well, $GIT_DIR/README.html was meant as extension of simple project
description ($GIT_DIR/description or gitweb.description in config).
One paragraph of concise short description; something like projects
description on software hosting site like SourceForge or Savannah,
or software metric site like Ohloh, or software catalog/directory
like Freshmeat.  It is meant as short introduction to project, or
to be more exact to given repository (see below).

In-tree README has different purpose.  Besides describing project
in detail, it usually has some instructions on how to install it
(even if it is referring to INSTALL file), how to configure it,
how to use it; should have all the things required by GNU Coding
Standards and/or Gnits Standards.  It is usually therefore much
longer than $GIT_DIR/README.html (and usually does not use HTML,
but [almost] plain text); so I think gitweb should display around
some given number of lines, ending at break between paragraph if
possible.

Besides $GIT_DIR/README.html can describe specific _repository_,
either some fork of a project (like who created it, what is purpose
of this fork, even if in-tree README remains the same; an example
would be git.git repository forks for git GSoC projects), or
specific mirror (for example describing difference between git.git
and alt-git.git on repo.or.cz).


But I would be not against having in-tree (with the mentioned caveat
of using top-tree HEAD version) README or README.html as fallback
if $GIT_DIR/README.html does not exists, taking into account some
order of preference among README* files if there exists more than one
such file, and displaying it not in full if in-tree README is large.

Alternate solution would be add some kind of _gitweb-admin_ script,
which would allow to set parameters of gitweb or of repository
displayed in gitweb on-line, which would include one-line plain-text
description of a project, and short README.html.  Although I'm
not sure if it should be not left for higher level of hosting site
(Gitorious, repo/Girocco, GitHub, Savane-clean, GForge,...).

-- 
Jakub Narebski
Poland