[PATCH/RFC] gitweb: Great subroutines renaming

[PATCH/RFC] gitweb: Great subroutines renaming

[Jakub Narebski]

This RFC is about better naming of subroutines in gitweb. The patch was
generated on top of 'next' (7c7e45d0cc0f482aeb19ecb0b56e9e7b65472c56)
using embedded gitweb-rename.sh script.


If one would want to apply patch which was generated without 
"subroutine renaming" on top of branch which includes it, simply
run gitweb-unrename.sh, apply patch, run gitweb-rename.sh, commit.

If one would want to apply patch which was created with new subroutine
names on top of branch which doesn not include "subroutine renaming"
commit, simply run gitweb-rename.sh, apply patch, run gitweb-unrename.sh,
then commit.

And in such a case patch calculus, with non-patch operators like those
scripts, is useful.


How should subroutines be named? Do you agree with proposal, or not?
Is such renaming usefull?

Comments? Thought?

-- >8 -- gitweb-rename.sh --
#/bin/sh

rm -f gitweb.perl.re~
echo "Great subroutine renaming"
perl -s -p -i.re~ \
	-e 's/\bgit_get_referencing\b/format_mark_referencing/;' \
	-e 's/\bgit_read_head\b/git_get_head/;' \
	-e 's/\bread_info_ref\b/git_read_info_refs/;' \
	-e 's/\bdate_str\b/parse_date/;' \
	-e 's/\bgit_read_tag\b/parse_tag/;' \
	-e 's/\bgit_read_commit\b/parse_commit/;' \
	-e 's/\bgit_blob_plain_mimetype\b/blob_plain_mimetype/;' \
	-e 's/\bgit_page_nav\b/git_print_page_nav/;' \
	-e 's/\bgit_header_div\b/git_print_header_div/;' \
	gitweb.perl

# end of gitweb-rename.sh

-- >8 -- gitweb-unrename.sh --
#/bin/sh

rm -f gitweb.perl.un~
echo "Reverting Great subroutine renaming"
perl -s -p -i.un~ \
	-e 's/\bformat_mark_referencing\b/git_get_referencing/;' \
	-e 's/\bgit_get_head\b/git_read_head/;' \
	-e 's/\bgit_read_info_refs\b/read_info_ref/;' \
	-e 's/\bparse_date\b/date_str/;' \
	-e 's/\bparse_tag\b/git_read_tag/;' \
	-e 's/\bparse_commit\b/git_read_commit/;' \
	-e 's/\bblob_plain_mimetype\b/git_blob_plain_mimetype/;' \
	-e 's/\bgit_print_page_nav\b/git_page_nav/;' \
	-e 's/\bgit_print_header_div\b/git_header_div/;' \
	gitweb.perl

# end of gitweb-unrename.sh
+++
From 73aac631709c11d01ac36a1f3f8c8ea3d1591b4d Mon Sep 17 00:00:00 2001
From: Jakub Narebski <jnareb@gmail.com>
Date: Mon, 7 Aug 2006 15:32:07 +0200
Subject: [PATCH] gitweb: Great subroutines renaming

Rename some of subroutines to better reflect what they do.
Some renames were not performed because subroutine name
reflects hash key.

Subroutines name guideline:
* git_ prefix for subroutines related to git commands,
  or to gitweb actions
* git_get_ prefix for subroutines calling git command
  and returning some output
* git_read_ prefix for subroutines directly accessing git
  repository files
* parse_ prefix for subroutines parsing some text, or reading and
  parsing some text into hash or list
* format_ prefix for subroutines formatting/post-processing some
  HTML/text fragment
* _get_ infix for subroutines which return result
* _print_ infix for subroutines which print fragment of output
* _body suffix for subroutines which outputs main part (body)
  of related action
* _nav suffix for subroutines related to navigation bars
* _div suffix for subroutines returning or ptinting div element

Renames:
- git_get_referencing => format_mark_referencing
- git_read_head => git_get_head
- read_info_ref => git_read_info_refs
- date_str => parse_date
- git_read_tag => parse_tag
- git_read_commit => parse_commit
- git_blob_plain_mimetype => blob_plain_mimetype
- git_page_nav => git_print_page_nav
- git_header_div => git_print_header_div

Signed-off-by: Jakub Narebski <jnareb@gmail.com>
---
 gitweb/gitweb.perl |  218 ++++++++++++++++++++++++++--------------------------
 1 files changed, 109 insertions(+), 109 deletions(-)

diff --git a/gitweb/gitweb.perl b/gitweb/gitweb.perl
index b3bfc6b..d8dbd3d 100755
--- a/gitweb/gitweb.perl
+++ b/gitweb/gitweb.perl
@@ -362,7 +362,7 @@ sub format_log_line_html {
 }
 
 # format marker of refs pointing to given object
-sub git_get_referencing {
+sub format_mark_referencing {
 	my ($refs, $id) = @_;
 
 	if (defined $refs->{$id}) {
@@ -376,7 +376,7 @@ ## -------------------------------------
 ## git utility subroutines, invoking git commands
 
 # get HEAD ref of given project as hash
-sub git_read_head {
+sub git_get_head {
 	my $project = shift;
 	my $oENV = $ENV{'GIT_DIR'};
 	my $retval = undef;
@@ -511,7 +511,7 @@ sub git_read_projects {
 	return @list;
 }
 
-sub read_info_ref {
+sub git_read_info_refs {
 	my $type = shift || "";
 	my %refs;
 	# 5dc01c595e6c6ec9ccda4f6f69c131c0dd945f8c	refs/tags/v2.6.11
@@ -536,7 +536,7 @@ sub read_info_ref {
 ## ----------------------------------------------------------------------
 ## parse to hash functions
 
-sub date_str {
+sub parse_date {
 	my $epoch = shift;
 	my $tz = shift || "-0000";
 
@@ -561,7 +561,7 @@ sub date_str {
 	return %date;
 }
 
-sub git_read_tag {
+sub parse_tag {
 	my $tag_id = shift;
 	my %tag;
 	my @comment;
@@ -596,7 +596,7 @@ sub git_read_tag {
 	return %tag
 }
 
-sub git_read_commit {
+sub parse_commit {
 	my $commit_id = shift;
 	my $commit_text = shift;
 
@@ -716,10 +716,10 @@ sub git_read_refs {
 		$ref_item{'epoch'} = 0;
 		$ref_item{'age'} = "unknown";
 		if ($type eq "tag") {
-			my %tag = git_read_tag($ref_id);
+			my %tag = parse_tag($ref_id);
 			$ref_item{'comment'} = $tag{'comment'};
 			if ($tag{'type'} eq "commit") {
-				%co = git_read_commit($tag{'object'});
+				%co = parse_commit($tag{'object'});
 				$ref_item{'epoch'} = $co{'committer_epoch'};
 				$ref_item{'age'} = $co{'age_string'};
 			} elsif (defined($tag{'epoch'})) {
@@ -731,7 +731,7 @@ sub git_read_refs {
 			$ref_item{'name'} = $tag{'name'};
 			$ref_item{'refid'} = $tag{'object'};
 		} elsif ($type eq "commit"){
-			%co = git_read_commit($ref_id);
+			%co = parse_commit($ref_id);
 			$ref_item{'reftype'} = "commit";
 			$ref_item{'name'} = $ref_file;
 			$ref_item{'title'} = $co{'title'};
@@ -806,7 +806,7 @@ sub mimetype_guess {
 	return $mime;
 }
 
-sub git_blob_plain_mimetype {
+sub blob_plain_mimetype {
 	my $fd = shift;
 	my $filename = shift;
 
@@ -955,7 +955,7 @@ sub die_error {
 ## ----------------------------------------------------------------------
 ## functions printing or outputting HTML: navigation
 
-sub git_page_nav {
+sub git_print_page_nav {
 	my ($current, $suppress, $head, $treehead, $treebase, $extra) = @_;
 	$extra = '' if !defined $extra; # pager or formats
 
@@ -1022,7 +1022,7 @@ sub git_get_paging_nav {
 ## ......................................................................
 ## functions printing or outputting HTML: div
 
-sub git_header_div {
+sub git_print_header_div {
 	my ($action, $title, $hash, $hash_base) = @_;
 	my $rest = '';
 
@@ -1062,10 +1062,10 @@ sub git_shortlog_body {
 	my $alternate = 0;
 	for (my $i = $from; $i <= $to; $i++) {
 		my $commit = $revlist->[$i];
-		#my $ref = defined $refs ? git_get_referencing($refs, $commit) : '';
-		my $ref = git_get_referencing($refs, $commit);
-		my %co = git_read_commit($commit);
-		my %ad = date_str($co{'author_epoch'});
+		#my $ref = defined $refs ? format_mark_referencing($refs, $commit) : '';
+		my $ref = format_mark_referencing($refs, $commit);
+		my %co = parse_commit($commit);
+		my %ad = parse_date($co{'author_epoch'});
 		if ($alternate) {
 			print "<tr class=\"dark\">\n";
 		} else {
@@ -1289,12 +1289,12 @@ sub git_project_list {
 		die_error(undef, "No projects found");
 	}
 	foreach my $pr (@list) {
-		my $head = git_read_head($pr->{'path'});
+		my $head = git_get_head($pr->{'path'});
 		if (!defined $head) {
 			next;
 		}
 		$ENV{'GIT_DIR'} = "$projectroot/$pr->{'path'}";
-		my %co = git_read_commit($head);
+		my %co = parse_commit($head);
 		if (!%co) {
 			next;
 		}
@@ -1385,9 +1385,9 @@ sub git_project_list {
 
 sub git_summary {
 	my $descr = git_read_description($project) || "none";
-	my $head = git_read_head($project);
-	my %co = git_read_commit($head);
-	my %cd = date_str($co{'committer_epoch'}, $co{'committer_tz'});
+	my $head = git_get_head($project);
+	my %co = parse_commit($head);
+	my %cd = parse_date($co{'committer_epoch'}, $co{'committer_tz'});
 
 	my $owner;
 	if (-f $projects_list) {
@@ -1408,9 +1408,9 @@ sub git_summary {
 		$owner = get_file_owner("$projectroot/$project");
 	}
 
-	my $refs = read_info_ref();
+	my $refs = git_read_info_refs();
 	git_header_html();
-	git_page_nav('summary','', $head);
+	git_print_page_nav('summary','', $head);
 
 	print "<div class=\"title\">&nbsp;</div>\n";
 	print "<table cellspacing=\"0\">\n" .
@@ -1419,24 +1419,24 @@ sub git_summary {
 	      "<tr><td>last change</td><td>$cd{'rfc2822'}</td></tr>\n" .
 	      "</table>\n";
 
-	open my $fd, "-|", $GIT, "rev-list", "--max-count=17", git_read_head($project)
+	open my $fd, "-|", $GIT, "rev-list", "--max-count=17", git_get_head($project)
 		or die_error(undef, "Open git-rev-list failed");
 	my @revlist = map { chomp; $_ } <$fd>;
 	close $fd;
-	git_header_div('shortlog');
+	git_print_header_div('shortlog');
 	git_shortlog_body(\@revlist, 0, 15, $refs,
 	                  $cgi->a({-href => "$my_uri?" . esc_param("p=$project;a=shortlog")}, "..."));
 
 	my $taglist = git_read_refs("refs/tags");
 	if (defined @$taglist) {
-		git_header_div('tags');
+		git_print_header_div('tags');
 		git_tags_body($taglist, 0, 15,
 		              $cgi->a({-href => "$my_uri?" . esc_param("p=$project;a=tags")}, "..."));
 	}
 
 	my $headlist = git_read_refs("refs/heads");
 	if (defined @$headlist) {
-		git_header_div('heads');
+		git_print_header_div('heads');
 		git_heads_body($headlist, $head, 0, 15,
 		               $cgi->a({-href => "$my_uri?" . esc_param("p=$project;a=heads")}, "..."));
 	}
@@ -1445,11 +1445,11 @@ sub git_summary {
 }
 
 sub git_tag {
-	my $head = git_read_head($project);
+	my $head = git_get_head($project);
 	git_header_html();
-	git_page_nav('','', $head,undef,$head);
-	my %tag = git_read_tag($hash);
-	git_header_div('commit', esc_html($tag{'name'}), $hash);
+	git_print_page_nav('','', $head,undef,$head);
+	my %tag = parse_tag($hash);
+	git_print_header_div('commit', esc_html($tag{'name'}), $hash);
 	print "<div class=\"title_text\">\n" .
 	      "<table cellspacing=\"0\">\n" .
 	      "<tr>\n" .
@@ -1458,7 +1458,7 @@ sub git_tag {
 	      "<td class=\"link\">" . $cgi->a({-href => "$my_uri?" . esc_param("p=$project;a=$tag{'type'};h=$tag{'object'}")}, $tag{'type'}) . "</td>\n" .
 	      "</tr>\n";
 	if (defined($tag{'author'})) {
-		my %ad = date_str($tag{'epoch'}, $tag{'tz'});
+		my %ad = parse_date($tag{'epoch'}, $tag{'tz'});
 		print "<tr><td>author</td><td>" . esc_html($tag{'author'}) . "</td></tr>\n";
 		print "<tr><td></td><td>" . $ad{'rfc2822'} . sprintf(" (%02d:%02d %s)", $ad{'hour_local'}, $ad{'minute_local'}, $ad{'tz_local'}) . "</td></tr>\n";
 	}
@@ -1478,9 +1478,9 @@ sub git_blame2 {
 	my $ftype;
 	die_error(undef, "Permission denied") if (!git_get_project_config_bool ('blame'));
 	die_error('404 Not Found', "File name not defined") if (!$file_name);
-	$hash_base ||= git_read_head($project);
+	$hash_base ||= git_get_head($project);
 	die_error(undef, "Couldn't find base commit") unless ($hash_base);
-	my %co = git_read_commit($hash_base)
+	my %co = parse_commit($hash_base)
 		or die_error(undef, "Reading commit failed");
 	if (!defined $hash) {
 		$hash = git_get_hash_by_path($hash_base, $file_name, "blob")
@@ -1496,8 +1496,8 @@ sub git_blame2 {
 	my $formats_nav =
 		$cgi->a({-href => "$my_uri?" . esc_param("p=$project;a=blob;h=$hash;hb=$hash_base;f=$file_name")}, "blob") .
 		" | " . $cgi->a({-href => "$my_uri?" . esc_param("p=$project;a=blame;f=$file_name")}, "head");
-	git_page_nav('','', $hash_base,$co{'tree'},$hash_base, $formats_nav);
-	git_header_div('commit', esc_html($co{'title'}), $hash_base);
+	git_print_page_nav('','', $hash_base,$co{'tree'},$hash_base, $formats_nav);
+	git_print_header_div('commit', esc_html($co{'title'}), $hash_base);
 	git_print_page_path($file_name, $ftype);
 	my @rev_color = (qw(light dark));
 	my $num_colors = scalar(@rev_color);
@@ -1536,9 +1536,9 @@ sub git_blame {
 	my $fd;
 	die_error('403 Permission denied', "Permission denied") if (!git_get_project_config_bool ('blame'));
 	die_error('404 Not Found', "File name not defined") if (!$file_name);
-	$hash_base ||= git_read_head($project);
+	$hash_base ||= git_get_head($project);
 	die_error(undef, "Couldn't find base commit") unless ($hash_base);
-	my %co = git_read_commit($hash_base)
+	my %co = parse_commit($hash_base)
 		or die_error(undef, "Reading commit failed");
 	if (!defined $hash) {
 		$hash = git_get_hash_by_path($hash_base, $file_name, "blob")
@@ -1550,8 +1550,8 @@ sub git_blame {
 	my $formats_nav =
 		$cgi->a({-href => "$my_uri?" . esc_param("p=$project;a=blob;h=$hash;hb=$hash_base;f=$file_name")}, "blob") .
 		" | " . $cgi->a({-href => "$my_uri?" . esc_param("p=$project;a=blame;f=$file_name")}, "head");
-	git_page_nav('','', $hash_base,$co{'tree'},$hash_base, $formats_nav);
-	git_header_div('commit', esc_html($co{'title'}), $hash_base);
+	git_print_page_nav('','', $hash_base,$co{'tree'},$hash_base, $formats_nav);
+	git_print_header_div('commit', esc_html($co{'title'}), $hash_base);
 	git_print_page_path($file_name, 'blob');
 	print "<div class=\"page_body\">\n";
 	print <<HTML;
@@ -1619,10 +1619,10 @@ HTML
 }
 
 sub git_tags {
-	my $head = git_read_head($project);
+	my $head = git_get_head($project);
 	git_header_html();
-	git_page_nav('','', $head,undef,$head);
-	git_header_div('summary', $project);
+	git_print_page_nav('','', $head,undef,$head);
+	git_print_header_div('summary', $project);
 
 	my $taglist = git_read_refs("refs/tags");
 	if (defined @$taglist) {
@@ -1632,10 +1632,10 @@ sub git_tags {
 }
 
 sub git_heads {
-	my $head = git_read_head($project);
+	my $head = git_get_head($project);
 	git_header_html();
-	git_page_nav('','', $head,undef,$head);
-	git_header_div('summary', $project);
+	git_print_page_nav('','', $head,undef,$head);
+	git_print_header_div('summary', $project);
 
 	my $taglist = git_read_refs("refs/heads");
 	my $alternate = 0;
@@ -1648,7 +1648,7 @@ sub git_heads {
 sub git_blob_plain {
 	if (!defined $hash) {
 		if (defined $file_name) {
-			my $base = $hash_base || git_read_head($project);
+			my $base = $hash_base || git_get_head($project);
 			$hash = git_get_hash_by_path($base, $file_name, "blob")
 				or die_error(undef, "Error lookup file");
 		} else {
@@ -1659,7 +1659,7 @@ sub git_blob_plain {
 	open my $fd, "-|", $GIT, "cat-file", "blob", $hash
 		or die_error(undef, "Couldn't cat $file_name, $hash");
 
-	$type ||= git_blob_plain_mimetype($fd, $file_name);
+	$type ||= blob_plain_mimetype($fd, $file_name);
 
 	# save as filename, even when no $file_name is given
 	my $save_as = "$hash";
@@ -1681,7 +1681,7 @@ sub git_blob_plain {
 sub git_blob {
 	if (!defined $hash) {
 		if (defined $file_name) {
-			my $base = $hash_base || git_read_head($project);
+			my $base = $hash_base || git_get_head($project);
 			$hash = git_get_hash_by_path($base, $file_name, "blob")
 				or die_error(undef, "Error lookup file");
 		} else {
@@ -1691,14 +1691,14 @@ sub git_blob {
 	my $have_blame = git_get_project_config_bool ('blame');
 	open my $fd, "-|", $GIT, "cat-file", "blob", $hash
 		or die_error(undef, "Couldn't cat $file_name, $hash");
-	my $mimetype = git_blob_plain_mimetype($fd, $file_name);
+	my $mimetype = blob_plain_mimetype($fd, $file_name);
 	if ($mimetype !~ m/^text\//) {
 		close $fd;
 		return git_blob_plain($mimetype);
 	}
 	git_header_html();
 	my $formats_nav = '';
-	if (defined $hash_base && (my %co = git_read_commit($hash_base))) {
+	if (defined $hash_base && (my %co = parse_commit($hash_base))) {
 		if (defined $file_name) {
 			if ($have_blame) {
 				$formats_nav .= $cgi->a({-href => "$my_uri?" . esc_param("p=$project;a=blame;h=$hash;hb=$hash_base;f=$file_name")}, "blame") . " | ";
@@ -1709,8 +1709,8 @@ sub git_blob {
 		} else {
 			$formats_nav .= $cgi->a({-href => "$my_uri?" . esc_param("p=$project;a=blob_plain;h=$hash")}, "plain");
 		}
-		git_page_nav('','', $hash_base,$co{'tree'},$hash_base, $formats_nav);
-		git_header_div('commit', esc_html($co{'title'}), $hash_base);
+		git_print_page_nav('','', $hash_base,$co{'tree'},$hash_base, $formats_nav);
+		git_print_header_div('commit', esc_html($co{'title'}), $hash_base);
 	} else {
 		print "<div class=\"page_nav\">\n" .
 		      "<br/><br/></div>\n" .
@@ -1732,7 +1732,7 @@ sub git_blob {
 
 sub git_tree {
 	if (!defined $hash) {
-		$hash = git_read_head($project);
+		$hash = git_get_head($project);
 		if (defined $file_name) {
 			my $base = $hash_base || $hash;
 			$hash = git_get_hash_by_path($base, $file_name, "tree");
@@ -1748,16 +1748,16 @@ sub git_tree {
 	close $fd or die_error(undef, "Reading tree failed");
 	$/ = "\n";
 
-	my $refs = read_info_ref();
-	my $ref = git_get_referencing($refs, $hash_base);
+	my $refs = git_read_info_refs();
+	my $ref = format_mark_referencing($refs, $hash_base);
 	git_header_html();
 	my $base_key = "";
 	my $base = "";
 	my $have_blame = git_get_project_config_bool ('blame');
-	if (defined $hash_base && (my %co = git_read_commit($hash_base))) {
+	if (defined $hash_base && (my %co = parse_commit($hash_base))) {
 		$base_key = ";hb=$hash_base";
-		git_page_nav('tree','', $hash_base);
-		git_header_div('commit', esc_html($co{'title'}) . $ref, $hash_base);
+		git_print_page_nav('tree','', $hash_base);
+		git_print_header_div('commit', esc_html($co{'title'}) . $ref, $hash_base);
 	} else {
 		print "<div class=\"page_nav\">\n";
 		print "<br/><br/></div>\n";
@@ -1813,14 +1813,14 @@ sub git_tree {
 }
 
 sub git_log {
-	my $head = git_read_head($project);
+	my $head = git_get_head($project);
 	if (!defined $hash) {
 		$hash = $head;
 	}
 	if (!defined $page) {
 		$page = 0;
 	}
-	my $refs = read_info_ref();
+	my $refs = git_read_info_refs();
 
 	my $limit = sprintf("--max-count=%i", (100 * ($page+1)));
 	open my $fd, "-|", $GIT, "rev-list", $limit, $hash
@@ -1831,21 +1831,21 @@ sub git_log {
 	my $paging_nav = git_get_paging_nav('log', $hash, $head, $page, $#revlist);
 
 	git_header_html();
-	git_page_nav('log','', $hash,undef,undef, $paging_nav);
+	git_print_page_nav('log','', $hash,undef,undef, $paging_nav);
 
 	if (!@revlist) {
-		my %co = git_read_commit($hash);
+		my %co = parse_commit($hash);
 
-		git_header_div('summary', $project);
+		git_print_header_div('summary', $project);
 		print "<div class=\"page_body\"> Last change $co{'age_string'}.<br/><br/></div>\n";
 	}
 	for (my $i = ($page * 100); $i <= $#revlist; $i++) {
 		my $commit = $revlist[$i];
-		my $ref = git_get_referencing($refs, $commit);
-		my %co = git_read_commit($commit);
+		my $ref = format_mark_referencing($refs, $commit);
+		my %co = parse_commit($commit);
 		next if !%co;
-		my %ad = date_str($co{'author_epoch'});
-		git_header_div('commit',
+		my %ad = parse_date($co{'author_epoch'});
+		git_print_header_div('commit',
 									 "<span class=\"age\">$co{'age_string'}</span>" .
 									 esc_html($co{'title'}) . $ref,
 									 $commit);
@@ -1883,12 +1883,12 @@ sub git_log {
 }
 
 sub git_commit {
-	my %co = git_read_commit($hash);
+	my %co = parse_commit($hash);
 	if (!%co) {
 		die_error(undef, "Unknown commit object");
 	}
-	my %ad = date_str($co{'author_epoch'}, $co{'author_tz'});
-	my %cd = date_str($co{'committer_epoch'}, $co{'committer_tz'});
+	my %ad = parse_date($co{'author_epoch'}, $co{'author_tz'});
+	my %cd = parse_date($co{'committer_epoch'}, $co{'committer_tz'});
 
 	my $parent = $co{'parent'};
 	if (!defined $parent) {
@@ -1904,22 +1904,22 @@ sub git_commit {
 	if ($hash =~ m/^[0-9a-fA-F]{40}$/) {
 		$expires = "+1d";
 	}
-	my $refs = read_info_ref();
-	my $ref = git_get_referencing($refs, $co{'id'});
+	my $refs = git_read_info_refs();
+	my $ref = format_mark_referencing($refs, $co{'id'});
 	my $formats_nav = '';
 	if (defined $file_name && defined $co{'parent'}) {
 		my $parent = $co{'parent'};
 		$formats_nav .= $cgi->a({-href => "$my_uri?" . esc_param("p=$project;a=blame;hb=$parent;f=$file_name")}, "blame");
 	}
 	git_header_html(undef, $expires);
-	git_page_nav('commit', defined $co{'parent'} ? '' : 'commitdiff',
+	git_print_page_nav('commit', defined $co{'parent'} ? '' : 'commitdiff',
 							 $hash, $co{'tree'}, $hash,
 							 $formats_nav);
 
 	if (defined $co{'parent'}) {
-		git_header_div('commitdiff', esc_html($co{'title'}) . $ref, $hash);
+		git_print_header_div('commitdiff', esc_html($co{'title'}) . $ref, $hash);
 	} else {
-		git_header_div('tree', esc_html($co{'title'}) . $ref, $co{'tree'}, $hash);
+		git_print_header_div('tree', esc_html($co{'title'}) . $ref, $co{'tree'}, $hash);
 	}
 	print "<div class=\"title_text\">\n" .
 	      "<table cellspacing=\"0\">\n";
@@ -2081,11 +2081,11 @@ sub git_commit {
 sub git_blobdiff {
 	mkdir($git_temp, 0700);
 	git_header_html();
-	if (defined $hash_base && (my %co = git_read_commit($hash_base))) {
+	if (defined $hash_base && (my %co = parse_commit($hash_base))) {
 		my $formats_nav =
 			$cgi->a({-href => "$my_uri?" . esc_param("p=$project;a=blobdiff_plain;h=$hash;hp=$hash_parent")}, "plain");
-		git_page_nav('','', $hash_base,$co{'tree'},$hash_base, $formats_nav);
-		git_header_div('commit', esc_html($co{'title'}), $hash_base);
+		git_print_page_nav('','', $hash_base,$co{'tree'},$hash_base, $formats_nav);
+		git_print_header_div('commit', esc_html($co{'title'}), $hash_base);
 	} else {
 		print "<div class=\"page_nav\">\n" .
 		      "<br/><br/></div>\n" .
@@ -2111,7 +2111,7 @@ sub git_blobdiff_plain {
 
 sub git_commitdiff {
 	mkdir($git_temp, 0700);
-	my %co = git_read_commit($hash);
+	my %co = parse_commit($hash);
 	if (!%co) {
 		die_error(undef, "Unknown commit object");
 	}
@@ -2128,13 +2128,13 @@ sub git_commitdiff {
 	if ($hash =~ m/^[0-9a-fA-F]{40}$/) {
 		$expires = "+1d";
 	}
-	my $refs = read_info_ref();
-	my $ref = git_get_referencing($refs, $co{'id'});
+	my $refs = git_read_info_refs();
+	my $ref = format_mark_referencing($refs, $co{'id'});
 	my $formats_nav =
 		$cgi->a({-href => "$my_uri?" . esc_param("p=$project;a=commitdiff_plain;h=$hash;hp=$hash_parent")}, "plain");
 	git_header_html(undef, $expires);
-	git_page_nav('commitdiff','', $hash,$co{'tree'},$hash, $formats_nav);
-	git_header_div('commit', esc_html($co{'title'}) . $ref, $hash);
+	git_print_page_nav('commitdiff','', $hash,$co{'tree'},$hash, $formats_nav);
+	git_print_header_div('commit', esc_html($co{'title'}) . $ref, $hash);
 	print "<div class=\"page_body\">\n";
 	my $comment = $co{'comment'};
 	my $empty = 0;
@@ -2200,7 +2200,7 @@ sub git_commitdiff {
 
 sub git_commitdiff_plain {
 	mkdir($git_temp, 0700);
-	my %co = git_read_commit($hash);
+	my %co = parse_commit($hash);
 	if (!%co) {
 		die_error(undef, "Unknown commit object");
 	}
@@ -2214,7 +2214,7 @@ sub git_commitdiff_plain {
 
 	# try to figure out the next tag after this commit
 	my $tagname;
-	my $refs = read_info_ref("tags");
+	my $refs = git_read_info_refs("tags");
 	open $fd, "-|", $GIT, "rev-list", "HEAD";
 	my @commits = map { chomp; $_ } <$fd>;
 	close $fd;
@@ -2228,7 +2228,7 @@ sub git_commitdiff_plain {
 	}
 
 	print $cgi->header(-type => "text/plain", -charset => 'utf-8', '-content-disposition' => "inline; filename=\"git-$hash.patch\"");
-	my %ad = date_str($co{'author_epoch'}, $co{'author_tz'});
+	my %ad = parse_date($co{'author_epoch'}, $co{'author_tz'});
 	my $comment = $co{'comment'};
 	print "From: $co{'author'}\n" .
 	      "Date: $ad{'rfc2822'} ($ad{'tz_local'})\n".
@@ -2264,17 +2264,17 @@ sub git_commitdiff_plain {
 
 sub git_history {
 	if (!defined $hash_base) {
-		$hash_base = git_read_head($project);
+		$hash_base = git_get_head($project);
 	}
 	my $ftype;
-	my %co = git_read_commit($hash_base);
+	my %co = parse_commit($hash_base);
 	if (!%co) {
 		die_error(undef, "Unknown commit object");
 	}
-	my $refs = read_info_ref();
+	my $refs = git_read_info_refs();
 	git_header_html();
-	git_page_nav('','', $hash_base,$co{'tree'},$hash_base);
-	git_header_div('commit', esc_html($co{'title'}), $hash_base);
+	git_print_page_nav('','', $hash_base,$co{'tree'},$hash_base);
+	git_print_header_div('commit', esc_html($co{'title'}), $hash_base);
 	if (!defined $hash && defined $file_name) {
 		$hash = git_get_hash_by_path($hash_base, $file_name);
 	}
@@ -2290,11 +2290,11 @@ sub git_history {
 	while (my $line = <$fd>) {
 		if ($line =~ m/^([0-9a-fA-F]{40})/){
 			my $commit = $1;
-			my %co = git_read_commit($commit);
+			my %co = parse_commit($commit);
 			if (!%co) {
 				next;
 			}
-			my $ref = git_get_referencing($refs, $commit);
+			my $ref = format_mark_referencing($refs, $commit);
 			if ($alternate) {
 				print "<tr class=\"dark\">\n";
 			} else {
@@ -2330,9 +2330,9 @@ sub git_search {
 		die_error(undef, "Text field empty");
 	}
 	if (!defined $hash) {
-		$hash = git_read_head($project);
+		$hash = git_get_head($project);
 	}
-	my %co = git_read_commit($hash);
+	my %co = parse_commit($hash);
 	if (!%co) {
 		die_error(undef, "Unknown commit object");
 	}
@@ -2351,8 +2351,8 @@ sub git_search {
 		$pickaxe_search = 1;
 	}
 	git_header_html();
-	git_page_nav('','', $hash,$co{'tree'},$hash);
-	git_header_div('commit', esc_html($co{'title'}), $hash);
+	git_print_page_nav('','', $hash,$co{'tree'},$hash);
+	git_print_header_div('commit', esc_html($co{'title'}), $hash);
 
 	print "<table cellspacing=\"0\">\n";
 	my $alternate = 0;
@@ -2370,7 +2370,7 @@ sub git_search {
 				next;
 			}
 			my @commit_lines = split "\n", $commit_text;
-			my %co = git_read_commit(undef, \@commit_lines);
+			my %co = parse_commit(undef, \@commit_lines);
 			if (!%co) {
 				next;
 			}
@@ -2451,7 +2451,7 @@ sub git_search {
 					print "</td>\n" .
 					      "</tr>\n";
 				}
-				%co = git_read_commit($1);
+				%co = parse_commit($1);
 			}
 		}
 		close $fd;
@@ -2461,14 +2461,14 @@ sub git_search {
 }
 
 sub git_shortlog {
-	my $head = git_read_head($project);
+	my $head = git_get_head($project);
 	if (!defined $hash) {
 		$hash = $head;
 	}
 	if (!defined $page) {
 		$page = 0;
 	}
-	my $refs = read_info_ref();
+	my $refs = git_read_info_refs();
 
 	my $limit = sprintf("--max-count=%i", (100 * ($page+1)));
 	open my $fd, "-|", $GIT, "rev-list", $limit, $hash
@@ -2486,8 +2486,8 @@ sub git_shortlog {
 
 
 	git_header_html();
-	git_page_nav('shortlog','', $hash,$hash,$hash, $paging_nav);
-	git_header_div('summary', $project);
+	git_print_page_nav('shortlog','', $hash,$hash,$hash, $paging_nav);
+	git_print_header_div('summary', $project);
 
 	git_shortlog_body(\@revlist, ($page * 100), $#revlist, $refs, $next_link);
 
@@ -2499,7 +2499,7 @@ ## feeds (RSS, OPML)
 
 sub git_rss {
 	# http://www.notestips.com/80256B3A007F2692/1/NAMO5P9UPQ
-	open my $fd, "-|", $GIT, "rev-list", "--max-count=150", git_read_head($project)
+	open my $fd, "-|", $GIT, "rev-list", "--max-count=150", git_get_head($project)
 		or die_error(undef, "Open git-rev-list failed");
 	my @revlist = map { chomp; $_ } <$fd>;
 	close $fd or die_error(undef, "Reading git-rev-list failed");
@@ -2514,12 +2514,12 @@ sub git_rss {
 
 	for (my $i = 0; $i <= $#revlist; $i++) {
 		my $commit = $revlist[$i];
-		my %co = git_read_commit($commit);
+		my %co = parse_commit($commit);
 		# we read 150, we always show 30 and the ones more recent than 48 hours
 		if (($i >= 20) && ((time - $co{'committer_epoch'}) > 48*60*60)) {
 			last;
 		}
-		my %cd = date_str($co{'committer_epoch'});
+		my %cd = parse_date($co{'committer_epoch'});
 		open $fd, "-|", $GIT, "diff-tree", '-r', $co{'parent'}, $co{'id'} or next;
 		my @difftree = map { chomp; $_ } <$fd>;
 		close $fd or next;
@@ -2569,12 +2569,12 @@ sub git_opml {
 
 	foreach my $pr (@list) {
 		my %proj = %$pr;
-		my $head = git_read_head($proj{'path'});
+		my $head = git_get_head($proj{'path'});
 		if (!defined $head) {
 			next;
 		}
 		$ENV{'GIT_DIR'} = "$projectroot/$proj{'path'}";
-		my %co = git_read_commit($head);
+		my %co = parse_commit($head);
 		if (!%co) {
 			next;
 		}
-- 
1.4.1.1

Re: [PATCH/RFC] gitweb: Great subroutines renaming

[Junio C Hamano]

Jakub Narebski <jnareb@gmail.com> writes:

> This RFC is about better naming of subroutines in gitweb. The patch was
> generated on top of 'next' (7c7e45d0cc0f482aeb19ecb0b56e9e7b65472c56)
> using embedded gitweb-rename.sh script.

> Subroutines name guideline:
> * git_ prefix for subroutines related to git commands,
>   or to gitweb actions
> * git_get_ prefix for subroutines calling git command
>   and returning some output
> * git_read_ prefix for subroutines directly accessing git
>   repository files

 - (I am not complaining or objecting yet -- this is just an
   observation. ) The distinction between git_get_foo and
   git_read_foo is an implementation detail.  The latter could
   signal that the implementation bypasses the published
   interface but depends on the implementation detail of the
   low-level git, so it might be a good idea, but on the other
   hand the only instance is git_read_info_refs which reads from
   .git/info/refs -- and its format is part of the published
   interface -- so I am not so sure this distinction is worth
   it.  And certainly we would not want to rely too heavily on
   the current implementation of the low-level git, so we
   obviously do not want to add more git_read_foo's needlessly,
   which makes me feel even less sure if we would want
   git_read_foo...

> * parse_ prefix for subroutines parsing some text, or reading and
>   parsing some text into hash or list
> * format_ prefix for subroutines formatting/post-processing some
>   HTML/text fragment
> * _get_ infix for subroutines which return result
> * _print_ infix for subroutines which print fragment of output
> * _body suffix for subroutines which outputs main part (body)
>   of related action
> * _nav suffix for subroutines related to navigation bars
> * _div suffix for subroutines returning or ptinting div element

 - All of these sound sane. 

> How should subroutines be named? Do you agree with proposal, or not?

I suspect that the list may disagree with some minor details on
the naming guidelines but I hope that everybody would in
principle be in favor of this.

> Is such renaming usefull?

If we are to have many more fixes and clean-ups on gitweb,
readable and consistent names would be very helpful.

The problem is when.  If we are going to apply this, we need to
pick a point of time when not many patches on gitweb are in
flight; otherwise I'd end up asking people to resend using new
names.

Re: [PATCH/RFC] gitweb: Great subroutines renaming

[Jakub Narebski]

Junio C Hamano wrote:

> Jakub Narebski <jnareb@gmail.com> writes:
> 
>> This RFC is about better naming of subroutines in gitweb. The patch was
>> generated on top of 'next' (7c7e45d0cc0f482aeb19ecb0b56e9e7b65472c56)
>> using embedded gitweb-rename.sh script.
[...]
>> * git_read_ prefix for subroutines directly accessing git
>>   repository files
> 
>  - (I am not complaining or objecting yet -- this is just an
>    observation. ) The distinction between git_get_foo and
>    git_read_foo is an implementation detail.  The latter could
>    signal that the implementation bypasses the published
>    interface but depends on the implementation detail of the
>    low-level git, so it might be a good idea, but on the other
>    hand the only instance is git_read_info_refs which reads from
>    .git/info/refs -- and its format is part of the published
>    interface -- so I am not so sure this distinction is worth
>    it.  And certainly we would not want to rely too heavily on
>    the current implementation of the low-level git, so we
>    obviously do not want to add more git_read_foo's needlessly,
>    which makes me feel even less sure if we would want
>    git_read_foo...

Currently after rename we have the following git_read_* functions

* git_read_info_refs, which reads .git/info/refs directly and relies on it's
format
* git_read_hash which translates ref to hash by reading ref file
(e.g. .git/refs/heads/master) which means that it doesn't support symrefs
yet; but first, it should be easy to implement without invoking any git
command, and second, there are usually no symrefs beside HEAD, and I'm not
sure that git would work with non-HEAD symref.
* git_read_refs (or rather git_readdir_refs) which reads .git/refs directory
* git_read_projects (or rather git_readdir_projects) which checks for
projects checking if HEAD file exists
* git_read_description which reads .git/description; but in the future
description might be stored in repository config

What is also important is the fast that git_read_* functions are fast,
with exception of git_read_info_refs...

[...]
> If we are to have many more fixes and clean-ups on gitweb,
> readable and consistent names would be very helpful.
> 
> The problem is when.  If we are going to apply this, we need to
> pick a point of time when not many patches on gitweb are in
> flight; otherwise I'd end up asking people to resend using new
> names.

With two scripts attached to the first post in this thread it would be
simple to apply pre-rename patch, by converting gitweb to pre-rename using
gitweb-unrename.sh script, then applying patch, then restoring new names
using gitweb-rename.sh script, and finally comitting changes (or amending
commit).

But I agree that it would be best to do "subroutine renaming" during lull in
gitweb development.

-- 
Jakub Narebski
Warsaw, Poland
ShadeHawk on #git

Re: [PATCH/RFC] gitweb: Great subroutines renaming

[Jakub Narebski]

Jakub Narebski wrote:

> What is also important is the fast that git_read_* functions are fast,
> with exception of git_read_info_refs...

I meant git_read_refs, which also does refs parsing, which is needed only to
get epoch information to sort refs by epoch, and discard most of them. This
makes summary and tags slow, so matled proposed caching (or extending
info/refs, or making equivalent of info/refs) this information on #git.

-- 
Jakub Narebski
Warsaw, Poland
ShadeHawk on #git

Re: [PATCH/RFC] gitweb: Great subroutines renaming

[Junio C Hamano]

Jakub Narebski <jnareb@gmail.com> writes:

> Currently after rename we have the following git_read_* functions
>
> * git_read_info_refs, which reads .git/info/refs directly and relies on it's
> format
> * git_read_hash which translates ref to hash by reading ref file
> (e.g. .git/refs/heads/master) which means that it doesn't support symrefs
> yet; but first, it should be easy to implement without invoking any git
> command, and second, there are usually no symrefs beside HEAD, and I'm not
> sure that git would work with non-HEAD symref.
> * git_read_refs (or rather git_readdir_refs) which reads .git/refs directory
> * git_read_projects (or rather git_readdir_projects) which checks for
> projects checking if HEAD file exists
> * git_read_description which reads .git/description; but in the future
> description might be stored in repository config
>
> What is also important is the fast that git_read_* functions are fast,
> with exception of git_read_info_refs...

Hmph.  readdir-refs is quite bad for future compatibility, so is
read_hash.

If you want _fast_ then make the implementation fast (or leave
room to make it fast later); encoding the fastness assumption in
the name IS WRONG.

For example, sub git_get_hash (not git_read_hash) can stay as
(potentially buggy wrt symrefs) "reading from .git/refs/$thing"
or could even be fixed to read from git-rev-parse (which is the
kosher way).  If it turns out to be a bottleneck, it could be
rewritten using Git.xs.  The same thing for read_refs which I
think should be doing ls-remote on the repository if it wants to
be kosher.

>> The problem is when...
>
> With two scripts attached to the first post in this thread it would be
> simple to apply pre-rename patch, by converting gitweb to pre-rename using
> gitweb-unrename.sh script, then applying patch, then restoring new names
> using gitweb-rename.sh script, and finally comitting changes (or amending
> commit).

That assumes the rename be done now, and nobody introduces new
functions following old naming convention in the meantime.

Re: [PATCH/RFC] gitweb: Great subroutines renaming

[Jakub Narebski]

Junio C Hamano wrote:

> Jakub Narebski <jnareb@gmail.com> writes: 

>> What is also important is the fast that git_read_* functions are fast,
>> with exception of git_read_info_refs...
> 
> Hmph.  readdir-refs is quite bad for future compatibility, so is
> read_hash.

Fast = doesn't call git commands, so no delay for fork+exec.

> If you want _fast_ then make the implementation fast (or leave
> room to make it fast later); encoding the fastness assumption in
> the name IS WRONG.

Matthias Lederhofer has noticed that parsing all the tags in "summary" and
"tags" views, while we use only epoch/timestamp information to sort them
and discard most of parsed input, is bottleneck due to the fact that
usually number of tags is linear with history (version tags) and the fact
that for each tag is one invocation of git (one fork, two execs).

> For example, sub git_get_hash (not git_read_hash) can stay as
> (potentially buggy wrt symrefs) "reading from .git/refs/$thing"
> or could even be fixed to read from git-rev-parse (which is the
> kosher way).  If it turns out to be a bottleneck, it could be
> rewritten using Git.xs.  The same thing for read_refs which I
> think should be doing ls-remote on the repository if it wants to
> be kosher.

True. So _read_ based on actually reading the files is out.
git_get_hash_by_ref, git_get_HEAD_hash (or just git_get_ref, git_get_head)
return single scalar value; git_read_info_refs and git_read_refs return
reference to hash or array, while git_read_projects returns array.

So the new guidelines would be:
* git_get_ prefix for subroutines related to git repository
  and returning single scalar (single value).
* git_read_ prefix for subroutines related to git repository, reading some
  files or multiline output, and returning hash reference, or list
  reference, or list.

-- 
Jakub Narebski
Warsaw, Poland
ShadeHawk on #git

Re: [PATCH/RFC] gitweb: Great subroutines renaming

[Jakub Narebski]

Jakub Narebski wrote:

> True. So _read_ based on actually reading the files is out.
> git_get_hash_by_ref, git_get_HEAD_hash (or just git_get_ref, git_get_head)
Or git_get_hash, git_get_head_hash

-- 
Jakub Narebski
Warsaw, Poland
ShadeHawk on #git

Re: [PATCH/RFC] gitweb: Great subroutines renaming

[Junio C Hamano]

Jakub Narebski <jnareb@gmail.com> writes:

> Matthias Lederhofer has noticed that parsing all the tags in "summary" and
> "tags" views, while we use only epoch/timestamp information to sort them
> and discard most of parsed input, is bottleneck due to the fact that
> usually number of tags is linear with history (version tags) and the fact
> that for each tag is one invocation of git (one fork, two execs).

Maybe we would want to expose for_each_ref somehow to the
command level then.  Looking at how "git branch" without any
argument lists the branches, and how "git tag -l" lists the
tags, it appears that we could benefit from such a command [*1*].

Of course doing it in Git.xs to make a single C level call is
easy, but that would benefit only Perl scripts, so it is not a
very good general solution.

> So the new guidelines would be:
> * git_get_ prefix for subroutines related to git repository
>   and returning single scalar (single value).
> * git_read_ prefix for subroutines related to git repository, reading some
>   files or multiline output, and returning hash reference, or list
>   reference, or list.

I would suggest to use git_get for both, unless there is a good
reason to differenciate them, since I do not understand why you
would want to differenciate one value vs multivalue.

-- >8 -- [*1*] -- >8 --
[PATCH] git-show-refs

Implementation is left as an exercise ;-)

---
diff --git a/Documentation/git-show-refs.txt b/Documentation/git-show-refs.txt
new file mode 100644
index 0000000..e2869e0
--- /dev/null
+++ b/Documentation/git-show-refs.txt
@@ -0,0 +1,96 @@
+git-show-refs(1)
+================
+
+NAME
+----
+git-show-refs - Lists refs in various formats
+
+SYNOPSIS
+--------
+'git-show-refs' [--count=<max>] [--sort=<sortkeys>] [--format=<format>] [<pattern>]
+
+DESCRIPTION
+-----------
+
+Iterate over refs under `$GIT_DIR/refs` that match `<pattern>`
+and show them according to the given `<format>`, after sorting
+them according to the given `<sortkeys>`.  If `<max>` is given,
+stop after showing that many refs.
+
+OPTIONS
+-------
+<max>::
+	By default the command shows all refs that match
+	`<pattern>`.  This option makes it stop after showing
+	that many refs.
+
+<sortkeys>::
+	Comma separated field names to sort on.  Prefix `-` to
+	sort in descending order of the value.  When
+	unspecified, `name` is used.
+
+<format>::
+	A string that interpolates `%(field name)` from the
+	object pointed at by a ref being shown.  When
+	unspecified, `%(name)` is used.
+
+<pattern>::
+	If given, the name of the ref is matched against this
+	using fnmatch(3).  Refs that do not match the pattern
+	are not shown.
+
+
+FIELD NAMES
+-----------
+
+Various values from structured fields in referenced objects can
+be used to interpolate into the resulting output, or as sort
+keys.
+
+For all objects, the following names can be used:
+
+name::
+	The name of the ref (the part after $GIT_DIR/refs/),
+	except that when `<pattern>` is used, the leading fixed
+	string part of `<pattern>` is stripped out.
+
+objecttype::
+	The type of the object (`blob`, `tree`, `commit`, `tag`)
+
+objectsize::
+	The size of the object (the same as `git-cat-file -s` reports).
+
+objectname::
+	The object name (aka SHA-1).
+
+In addition, for commit and tag objects, the header field names
+(`tree`, `parent`, `object`, `type`, and `tag`) can be used to
+specify the value in the header field.  Fields that have
+name-email-date tuple as its value (`author`, `committer`, and
+`tagger`) can be suffixed with `name`, `email`, and `date` to
+extract the named component.  The first line of a commit and tag
+object can be referred to with `subject`, the remaining lines
+with `body`, and both (including the typical blank line after
+`subject`) with `contents`.
+
+Also a pseudo field name `ishead` can be used to check if the
+ref is pointed by `$GIT_DIR/HEAD` pointer.  The field
+interpolates as "* " if true, otherwise an empty string.
+
+For sorting purposes, fields with numeric values sort in numeric
+order (`objectsize`, `authordate`, `committerdate`, `taggerdate`).
+All other fields are used to sort in their byte-value order.
+
+
+EXAMPLES
+--------
+
+Show most recent 16 tags for consumption by gitweb::
+	git-show-refs --count=16 --sort=-taggerdate,name \
+		--format='%(taggerdate) %(name)\t%(tag)\t%(subject)' 'tags/*'
+
+`git-branch` without argument::
+	git-show-refs --format='%(ishead)%(name)' 'heads/*'
+
+`git-tag -l`::
+	git-show-refs tags/*

Re: [PATCH/RFC] gitweb: Great subroutines renaming

[Jakub Narebski]

Junio C Hamano wrote:

> Jakub Narebski <jnareb@gmail.com> writes:

>> So the new guidelines would be:
>> * git_get_ prefix for subroutines related to git repository
>>   and returning single scalar (single value).
>> * git_read_ prefix for subroutines related to git repository, reading some
>>   files or multiline output, and returning hash reference, or list
>>   reference, or list.
> 
> I would suggest to use git_get for both, unless there is a good
> reason to differenciate them, since I do not understand why you
> would want to differenciate one value vs multivalue.

I'd rather have git_read_info_refs, because it _reads_ info/refs file, 
and git_read_refs as opposed to git_get_hash/git_get_ref/git_ref_to_hash
(or hash_from_ref). I'm not sure about git_read_projects vs. perhaps
git_get_project_list or git_list_projects. Neither about 
git_read_description vs. git_get_project_description

-- 
Jakub Narebski
Warsaw, Poland
ShadeHawk on #git

Re: [PATCH/RFC] gitweb: Great subroutines renaming

[Jakub Narebski]

Junio C Hamano wrote:

> +git-show-refs(1)
> +================
> +
> +NAME
> +----
> +git-show-refs - Lists refs in various formats
[...]
> +EXAMPLES
> +--------
> +
> +Show most recent 16 tags for consumption by gitweb::
> +     git-show-refs --count=16 --sort=-taggerdate,name \
> +             --format='%(taggerdate) %(name)\t%(tag)\t%(subject)' 'tags/*'
> +
> +`git-branch` without argument::
> +     git-show-refs --format='%(ishead)%(name)' 'heads/*'
> +
> +`git-tag -l`::
> +     git-show-refs tags/*

`git-ls-remotes .` is suspiciously missing from the examples.

Format needs to somewhat incorporate line for referencing object for that, 
if it exists.

-- 
Jakub Narebski
Warsaw, Poland
ShadeHawk on #git

Re: [PATCH/RFC] gitweb: Great subroutines renaming

[Jakub Narebski]

Jakub Narebski wrote:

> With two scripts attached to the first post in this thread it would be
> simple to apply pre-rename patch, by converting gitweb to pre-rename using
> gitweb-unrename.sh script, then applying patch, then restoring new names
> using gitweb-rename.sh script, and finally comitting changes (or amending
> commit).

Or just apply corrected gitweb-rename.sh script (see below) to patch (mbox),
and then apply and commit the "after rename" patch.

#!/bin/sh

if test -z "$1"; then
        FILE=`git rev-parse --show-cdup`gitweb/gitweb.perl
else
        FILE=$1
fi

echo "Great subroutine renaming: $FILE"
perl -s -p -i.re~ \
        -e 's/\bgit_get_referencing\b/format_mark_referencing/;' \
        -e 's/\bgit_read_head\b/git_get_head/;' \
        -e 's/\bread_info_ref\b/git_read_info_refs/;' \
        -e 's/\bdate_str\b/parse_date/;' \
        -e 's/\bgit_read_tag\b/parse_tag/;' \
        -e 's/\bgit_read_commit\b/parse_commit/;' \
        -e 's/\bgit_blob_plain_mimetype\b/blob_plain_mimetype/;' \
        -e 's/\bgit_page_nav\b/git_print_page_nav/;' \
        -e 's/\bgit_header_div\b/git_print_header_div/;' \
        "$FILE"

# end of gitweb-rename.sh

-- 
Jakub Narebski
Warsaw, Poland
ShadeHawk on #git

Re: [PATCH/RFC] gitweb: Great subroutines renaming

[Jakub Narebski]

Junio C Hamano wrote:


> +`git-branch` without argument::
> +     git-show-refs --format='%(ishead)%(name)' 'heads/*'

        git-show-refs --format='%(ishead?"* ":"  ")%(name)' 'refs/heads/*'

-- 
Jakub Narebski
Warsaw, Poland
ShadeHawk on #git

Re: git-show-refs (was: [PATCH/RFC] gitweb: Great subroutines renaming)

[Jakub Narebski]

Junio C Hamano wrote:

> +<format>::
> +       A string that interpolates `%(field name)` from the
> +       object pointed at by a ref being shown.  When
> +       unspecified, `%(name)` is used.

Wouldn't it be better to (re)use notation of rpm's --query-format, 
i.e. use %{name}, or %30{name}, or %-30{name} for single scalar values,
use :typetag output formats, like ':date' (Use strftime(3) "%c" format.) and
':day' (Use strftime(3) "%a %b %d %Y" format.) for epoch/timestamp field,
use square brackets for iterating over multivalue output, e.g.
"[parent: %{parent}]" for writing out all parents, etc.

Perhaps we could even borrow some code...

-- 
Jakub Narebski
Warsaw, Poland
ShadeHawk on #git

Re: [PATCH/RFC] gitweb: Great subroutines renaming

[Junio C Hamano]

Jakub Narebski <jnareb@gmail.com> writes:

> `git-ls-remotes .` is suspiciously missing from the examples.

Because the point of show-refs was not to replace it only for
the local case.

> Format needs to somewhat incorporate line for referencing object for that, 
> if it exists.

Also I do not think you would want "ref^{}" style dereferencing
ls-remotes does for gitweb anyway.

What gitweb might want is "what type of object is this tag
pointing at" and "what is the object pointed at by this tag"
(both used on "Tags" list).  I think show-refs specification
allows you to do that inexpensively.

> Wouldn't it be better to (re)use notation of rpm's --query-format, 
> i.e. use %{name}, or %30{name}, or %-30{name} for single scalar values,
> use :typetag output formats,...

I did not do them because these enhancements are not needed to
unblock you from optimizing git_get_* calls in gitweb.  These
enhancement can come later as long as the initial syntax is
simple, clean and extensible enough, which I think it is.

Re: [PATCH/RFC] gitweb: Great subroutines renaming

[Jakub Narebski]

Junio C Hamano wrote:

> Jakub Narebski <jnareb@gmail.com> writes:
> 

>> Wouldn't it be better to (re)use notation of rpm's --query-format, 
>> i.e. use %{name}, or %30{name}, or %-30{name} for single scalar values,
>> use :typetag output formats,...
> 
> I did not do them because these enhancements are not needed to
> unblock you from optimizing git_get_* calls in gitweb.  These
> enhancement can come later as long as the initial syntax is
> simple, clean and extensible enough, which I think it is.

Yes, that's true. I'm wondering if %(fieldname) of %{fieldname} would be
better.

-- 
Jakub Narebski
Warsaw, Poland
ShadeHawk on #git

Re: [PATCH/RFC] gitweb: Great subroutines renaming

[Jakub Narebski]

Jakub Narebski wrote:

> Renames:
> - git_get_referencing => format_mark_referencing
> - git_read_head => git_get_head
> - read_info_ref => git_read_info_refs
> - date_str => parse_date
> - git_read_tag => parse_tag
> - git_read_commit => parse_commit
> - git_blob_plain_mimetype => blob_plain_mimetype
> - git_page_nav => git_print_page_nav
> - git_header_div => git_print_header_div

Summary of discussion: using *_read_* to distinguish between git calling
commands, and file reading commands is not a good idea. So now the
guideline is to be more fluid with *_get_* vs *_read_* subroutine naming:
it would depend on the noun after _get_ or _read_.


Proposed renames:
1. Renames I think everybody would agree on
 - git_get_referencing => format_mark_referencing

 - date_str => parse_date
 - git_read_tag => parse_tag
 - git_read_commit => parse_commit

 - git_blob_plain_mimetype => blob_plain_mimetype

 - git_page_nav => git_print_page_nav
 - git_header_div => git_print_header_div


2. Renames about which I'm less sure
 - git_read_head => git_get_head_hash
 - git_read_hash => git_get_hash_by_ref

 - git_read_description => git_project_description
 - git_read_projects => git_get_projects_list or git_list_projects

 - read_info_ref => git_read_info_refs => git_get_references
 (this one depend too much on implementation, which might be changed to 
  parsing 'git ls-remotes .' output instead of relying on info/refs being
  up to date thanks to git-update-server-info in post-update hook, 
  and on its format).

 - age_string => ????
 (it returns 'nn ago' string)


Thoughts? Comments? I'm especially interested in answer of other people
working on gitweb (Luben Tuikov, Matthias Lederhofer, Jeff King,  
Sham Chukoury, and others).

-- 
Jakub Narebski
Warsaw, Poland
ShadeHawk on #git

Re: [PATCH/RFC] gitweb: Great subroutines renaming

[Junio C Hamano]

Jakub Narebski <jnareb@gmail.com> writes:

> Summary of discussion: using *_read_* to distinguish between git calling
> commands, and file reading commands is not a good idea. So now the
> guideline is to be more fluid with *_get_* vs *_read_* subroutine naming:
> it would depend on the noun after _get_ or _read_.

I suspect it is summary of discussion between you and yourself ;-).

I still do not think get_* vs read_* mean anything.  You get
information somehow, and maybe reading from a pre-existing file
might be one way to do so, or reading from a pipe to a command
might be another way to do so, but it does not change an iota
that you are retrieving information.

> Proposed renames:
> 1. Renames I think everybody would agree on
>  - git_get_referencing => format_mark_referencing
>
>  - date_str => parse_date
>  - git_read_tag => parse_tag
>  - git_read_commit => parse_commit
>
>  - git_blob_plain_mimetype => blob_plain_mimetype

Does it matter that the function is used in blob-plain?  In
other words, how would this function, blob-plain-mimetype, be
different if we were to have another function called blob-mimetype?

How about calling it "guess-mimetype"?

>  - git_page_nav => git_print_page_nav
>  - git_header_div => git_print_header_div

Both sounds sane (I would have said "git-show-blah" if I were
doing this myself, though).

>  - git_read_head => git_get_head_hash
>  - git_read_hash => git_get_hash_by_ref

Both sounds sane.

>  - git_read_description => git_project_description

No verbs in the renamed one feels awkward.
git-get-project-description, perhaps.

>  - git_read_projects => git_get_projects_list or git_list_projects

list-projects is probably the most natural name for something
that gives a list to the end user.  If you are getting the list
in-core for further processing, the name is misleading.

Perhaps git-get-projects-list is more appropriate.

>  - read_info_ref => git_read_info_refs => git_get_references
>  (this one depend too much on implementation, which might be changed to 
>   parsing 'git ls-remotes .' output instead of relying on info/refs being
>   up to date thanks to git-update-server-info in post-update hook, 
>   and on its format).

I am not worried too much about the format (because clone/fetch
over http depends on it), but reading from ls-remote self would
make it unnecessary to run update-server-info if a repo is not
served over http but is shown over gitweb.

>  - age_string => ????

Good name as is, but if you want consistent, it formats the
timestamp into age, so it would fall into format-blah family.

Re: [PATCH/RFC] gitweb: Great subroutines renaming

[Jakub Narebski]

Junio C Hamano wrote:

> Jakub Narebski <jnareb@gmail.com> writes:

>>  - git_blob_plain_mimetype => blob_plain_mimetype
> 
> Does it matter that the function is used in blob-plain?  In
> other words, how would this function, blob-plain-mimetype, be
> different if we were to have another function called blob-mimetype?
> 
> How about calling it "guess-mimetype"?

There are two functions, mimetype_guess_file and mimetype_guess, of which
first one gets mimetype of file based on specified mime.types like file,
second tries $mimetypes_file then '/etc/mime.types', while currently named
git_blob_plain_mimetype subroutine first tries mimetype_guess, then checks
if the file is text file (-T $fd) and if not uses some built in mime.types
rules. Perhaps current mimetype_guess could be embedded into current
git_blob_plain_mimetype.

All those subroutines need better names I think.
 
>>  - git_page_nav => git_print_page_nav
>>  - git_header_div => git_print_header_div
> 
> Both sounds sane (I would have said "git-show-blah" if I were
> doing this myself, though).

They are called among print statements. I'm not sure if some of them
wouldn't be better converted to format_* types subroutines.
 
>>  - read_info_ref => git_read_info_refs => git_get_references
>>  (this one depend too much on implementation, which might be changed to 
>>   parsing 'git ls-remotes .' output instead of relying on info/refs being
>>   up to date thanks to git-update-server-info in post-update hook, 
>>   and on its format).
> 
> I am not worried too much about the format (because clone/fetch
> over http depends on it), but reading from ls-remote self would
> make it unnecessary to run update-server-info if a repo is not
> served over http but is shown over gitweb.

Do the git_get_references for this subroutine, which returns hashref which
keys are ids, and values are refs pointing to the key id, sounds good?

-- 
Jakub Narebski
Warsaw, Poland
ShadeHawk on #git

Re: [PATCH/RFC] gitweb: Great subroutines renaming

[Jakub Narebski]

Junio C Hamano wrote:

> Jakub Narebski <jnareb@gmail.com> writes:
> 
>> Matthias Lederhofer has noticed that parsing all the tags in "summary" and
>> "tags" views, while we use only epoch/timestamp information to sort them
>> and discard most of parsed input, is bottleneck due to the fact that
>> usually number of tags is linear with history (version tags) and the fact
>> that for each tag is one invocation of git (one fork, two execs).
> 
> Maybe we would want to expose for_each_ref somehow to the
> command level then.  Looking at how "git branch" without any
> argument lists the branches, and how "git tag -l" lists the
> tags, it appears that we could benefit from such a command [*1*].

> -- >8 -- [*1*] -- >8 --
> [PATCH] git-show-refs
> 
> Implementation is left as an exercise ;-)
[...]
> +SYNOPSIS
> +--------
> +'git-show-refs' [--count=<max>] [--sort=<sortkeys>] [--format=<format>] [<pattern>]

It would be useful for application in gitweb to have [-l|--count-lines]
option which would print number of lines (excluding the one with number
of lines) before any output. It could be used to know before reading all
the output how many lines would be, and if there is something more than
(for --count=<max>) <max> lines. 

It is needed in gitweb to create pagination/paging navigation bar. 
Currently it is done by reading all the output into array, and 
checking length of this array.

While at it, --skip=<count> would also be nice, although not that
necessary.

-- 
Jakub Narebski
Warsaw, Poland
ShadeHawk on #git

Re: [PATCH/RFC] gitweb: Great subroutines renaming

[Junio C Hamano]

Jakub Narebski <jnareb@gmail.com> writes:

> It is needed in gitweb to create pagination/paging navigation bar. 
> Currently it is done by reading all the output into array, and 
> checking length of this array.

If you want to show 10 and do ... when you have more than that,
the standard technique is to ask for 11 ;-).

Re: [PATCH/RFC] gitweb: Great subroutines renaming

[Jakub Narebski]

Junio C Hamano wrote:

> Jakub Narebski <jnareb@gmail.com> writes:
> 
>> It is needed in gitweb to create pagination/paging navigation bar. 
>> Currently it is done by reading all the output into array, and 
>> checking length of this array.
> 
> If you want to show 10 and do ... when you have more than that,
> the standard technique is to ask for 11 ;-).

It's not a problem to do '...'/'next' link _after_ the body, but
the paging navigation bar is at the _top_ of page, before 
outputting the body. See e.g.
  http://www.kernel.org/git/?p=git/git.git;a=shortlog
there is "HEAD * prev * next" at the top, and "next" at the bottom
of the revision list.

-- 
Jakub Narebski
Warsaw, Poland
ShadeHawk on #git

Re: [PATCH/RFC] gitweb: Great subroutines renaming

[Junio C Hamano]

Jakub Narebski <jnareb@gmail.com> writes:

> It's not a problem to do '...'/'next' link _after_ the body, but
> the paging navigation bar is at the _top_ of page, before 
> outputting the body.

A good web engineering practice is to prepare the data before
you generate a single line of output, so after or top should not
make a difference, I would think.

Re: [PATCH/RFC] gitweb: Great subroutines renaming

[Jakub Narebski]

Subroutines in gitweb: <current name> => <proposed rename>.
If nobody would give any better suggestions, or warn about patches to gitweb
to be sent, could we do that "Great subroutines renaming" some time soon?
TIA.

* validate_input
* esc_param
* esc_html
* unquote
* untabify
* chop_str

* age_class
* age_string
* mode_str
* file_type

* format_log_line_html
* git_get_referencing => format_mark_referencing (???)

* git_read_head => git_get_head_hash
* git_read_hash => git_get_hash_by_ref
* git_get_hash_by_path
* git_get_type
* git_get_project_config
* git_get_project_config_bool
* git_read_description => git_get_project_description
* git_read_projects => git_get_projects_list
* read_info_ref => git_get_references
* git_read_refs => git_get_refs_list

* date_str => parse_date
* git_read_tag => parse_tag
* git_read_commit => parse_commit

* get_file_owner
* mimetype_guess_file => ??? (reads, parses and uses mime.types like file)
* mimetype_guess => (to be incorporated in blob_mimetype)
* git_blob_plain_mimetype => blob_mimetype
* git_get_paging_nav => ???
* git_page_nav => git_print_page_nav
* git_header_div => git_print_header_div
* git_print_page_path
* git_diff_print => (to be made obsolete)

* git_header_html
* git_footer_html
* die_error

* git_shortlog_body
* git_tags_body
* git_heads_body

* git_project_list
* git_summary
* git_tag
* git_blame2 => git_blame (?)
* git_blame => git_annotate (?)
* git_tags
* git_heads
* git_blob_plain
* git_blob
* git_tree
* git_log
* git_commit
* git_blobdiff
* git_blobdiff_plain
* git_commitdiff
* git_commitdiff_plain
* git_history
* git_search
* git_shortlog
* git_rss
* git_opml

-- 
Jakub Narebski
Warsaw, Poland
ShadeHawk on #git

Re: [PATCH/RFC] gitweb: Great subroutines renaming

[Junio C Hamano]

Jakub Narebski <jnareb@gmail.com> writes:

> Subroutines in gitweb: <current name> => <proposed rename>.

If it is not too much trouble, having a few line summary of what
each of the sub does would greatly help judging if the names are
appropriate.

Re: [PATCH/RFC] gitweb: Great subroutines renaming

[Jakub Narebski]

Junio C Hamano wrote:

> Jakub Narebski <jnareb@gmail.com> writes:
> 
>> Subroutines in gitweb: <current name> => <proposed rename>.
> 
> If it is not too much trouble, having a few line summary of what
> each of the sub does would greatly help judging if the names are
> appropriate.

Subroutines name guideline, revised:
* git_ prefix for subroutines related to git commands,
  or to gitweb actions
* git_get_ prefix for inner subroutines calling git command
  and returning some output
* parse_ prefix for subroutines parsing some text, or reading and
  parsing some text into hash or list
* format_ prefix for subroutines formatting/post-processing some
  HTML/text fragment
* _get_ infix for subroutines which return result
* _print_ infix for subroutines which print fragment of output
* _body suffix for subroutines which outputs main part (body)
  of related action
* _nav suffix for subroutines related to navigation bars
* _div suffix for subroutines returning or printing div element

Current gitweb subroutines, with proposed renames, and short summary.

* validate_input => is_valid_ref, is_valid_path (?)
  universal (too universal) parameter validation
* esc_param
  quote unsafe chars in link parameters
* esc_html
  escape to HTML, replace invalid uft8 characters
* unquote
  unquote filenames quoted and escaped by git
* untabify
  convert tabs (8 spaces wide tabstops) to spaces
* chop_str
  shorten string, removing characters entities as whole

* age_class
  CSS class for given age value (in seconds)
* age_string
  convert age in seconds to "nn units ago" string
* mode_str
  convert file mode in octal to symbolic file mode string
* file_type
  convert file mode in octal to file type string (directory, symlink,
  file, unknown)

* format_log_line_html
  format line of commit message or tag comment, hyperlinking commitids
  (perhaps in the future comittags, e.g. BUG(nn) support)
* git_get_referencing => format_mark_referencing (???)
  return HTML fragment generating marker of refs pointing to given object

* git_read_head => git_get_head_hash
  get HEAD ref of given project as hash
* git_read_hash => git_get_hash_by_ref
  get hash of given ref (e.g. refs/heads/next)
* git_get_hash_by_path
  get hash of given path at given ref
* git_get_type
  get type of given object (by hash)
* git_get_project_config
  return value of given variable in gitweb section
* git_get_project_config_bool
  return value of given variable in gitweb section, as boolean
* git_read_description => git_get_project_description
* git_read_projects => git_get_projects_list
  return list of projects (path, owner)
* read_info_ref => git_get_references
  return hashref of refs pointing to object given by hash key
* git_read_refs => git_get_refs_list
  list of hashrefs of parsed ref info
  (parsing to be separated into parse_ref subroutine)

* date_str => parse_date
  given epoch and (optionally) timezone return parsed date as hash
* git_read_tag => parse_tag
  given tag_id, return parsed tag as Perl hash
* git_read_commit => parse_commit
  given commit_id (and optionally commit_text to reuse), return parsed
commit

* get_file_owner
  return owner of given file, according to user id and gcos field
* mimetype_guess_file => ??? 
  reads and parses mime.types like file, return mimetype of given filename
* mimetype_guess => (to be incorporated in blob_mimetype)
  try $mimetypes_file, or /etc/mime.types
* git_blob_plain_mimetype => blob_mimetype
  return mimetype of given (by file descriptor and filename) blob
* git_get_paging_nav => ???
  return HTML fragment generating "HEAD * prev * next" page navigation
* git_page_nav => git_print_page_nav
  print "action" navigation bar, optionally with pager or formats below
* git_header_div => git_print_header_div
  prints div element of class "header" just below navigation bar
* git_print_page_path
  print div element of class "page_path" with current path
* git_diff_print => (to be made obsolete)
  print diff between two files, using /usr/bin/diff and temporary files

* git_header_html
  prints HTML header of gitweb output 
* git_footer_html
  prints HTML footer of gitweb output
* die_error
  prints gitweb error page

Subroutines printing table with shortlog, tags, heads respectively
* git_shortlog_body
* git_tags_body
* git_heads_body

Action subroutines
* git_project_list
* git_summary
* git_tag
* git_blame2 => git_blame (?)
* git_blame => git_annotate (?)
* git_tags
* git_heads
* git_blob_plain
* git_blob
* git_tree
* git_log
* git_commit
* git_blobdiff
* git_blobdiff_plain
* git_commitdiff
* git_commitdiff_plain
* git_history
* git_search
* git_shortlog
* git_rss
* git_opml

-- 
Jakub Narebski
Warsaw, Poland
ShadeHawk on #git

Re: [PATCH/RFC] gitweb: Great subroutines renaming

[Jakub Narebski]

I have series of gitweb patches to send: should I make them pre-rename, or
post-rename?

-- 
Jakub Narebski
Warsaw, Poland
ShadeHawk on #git

Re: [PATCH/RFC] gitweb: Great subroutines renaming

[Junio C Hamano]

Jakub Narebski <jnareb@gmail.com> writes:

> I have series of gitweb patches to send: should I make them pre-rename, or
> post-rename?

Do people happy with the general naming guidelines (I am)?

I'll be pushing out 1.4.2 this weekend, and then moving all the
gitweb stuff pending in "next" to "master" after that.

Let's have the rename immediately on top of it first, then
continue cleaning up after that.

Re: [PATCH/RFC] gitweb: Great subroutines renaming

[Junio C Hamano]

Junio C Hamano <junkio@cox.net> writes:

> Jakub Narebski <jnareb@gmail.com> writes:
>
>> I have series of gitweb patches to send: should I make them pre-rename, or
>> post-rename?
>
> Do people happy with the general naming guidelines (I am)?

Ah, the sentence does not parse X-<.  Do people find them acceptable?

Re: [PATCH/RFC] gitweb: Great subroutines renaming

[Jakub Narebski]

Junio C Hamano wrote:

> Jakub Narebski <jnareb@gmail.com> writes:
> 
>> I have series of gitweb patches to send: should I make them pre-rename,
or
>> post-rename?
> 
> Do people happy with the general naming guidelines (I am)?
> 
> I'll be pushing out 1.4.2 this weekend, and then moving all the
> gitweb stuff pending in "next" to "master" after that.
> 
> Let's have the rename immediately on top of it first, then
> continue cleaning up after that.

So after 1.4.2 gitweb patches should be based on next, or on master?

-- 
Jakub Narebski
Warsaw, Poland
ShadeHawk on #git

Re: [PATCH/RFC] gitweb: Great subroutines renaming

[Junio C Hamano]

Jakub Narebski <jnareb@gmail.com> writes:

> Junio C Hamano wrote:
>
>> I'll be pushing out 1.4.2 this weekend, and then moving all the
>> gitweb stuff pending in "next" to "master" after that.
>> 
>> Let's have the rename immediately on top of it first, then
>> continue cleaning up after that.
>
> So after 1.4.2 gitweb patches should be based on next, or on master?

Well, since "git diff master next -- gitweb/" reports empty, the
question should not matter at this moment ;-).

Here are my preferences, as a general guideline:

 * If it is a general clean-up (e.g. changing a function
   signature declared in cache.h to tighten constness), I would
   prefer two patches; one to apply on "master", and another one
   created by assuming:

    - your first patch for "master" is accepted;
    - resulting "master" (with your first patch applied) will be
      merged into "next";

   Then the other patch is to clean-up the remaining stuff
   introduced between "master" and "next" (e.g. the function
   whose signature you changed in the first patch may have more
   call sites in "next" you may need to fix them up).

   If you know the specific topic I internally have (you can
   tell them by looking at the merge commits on "next"),
   separating the remainder patch into one per topic would be
   even nicer, but that is probably too much work to ask from
   contributors.

   Most of the time I can do this split myself, though, so it is
   Ok to send a patch to fix things up only in "master", and
   have me find out that it breaks "next", at that time I may
   fix things up myself similarly or I may ask you to send in a
   separete patch in similar spirit to fix up things in "next".

 * If it is a new series, I would prefer things be based on
   "master", unless you use some feature (either internal or
   external) that only exists in "next" or in "pu".

 * If it is a follow-up on stuff still in "next", obviously
   basing the patch on "master" is not possible.

 * If you have independent fix even though we have stuff that
   touch the same general area in "next", it is very much
   preferable if it applies to "master".  A critical fix for
   "next" that does not apply to "master" is taking the fix
   hostage to whatever is in "next".

 * If you need to base on "next", telling me why (i.e. "this
   uses such and such function which are not in master") helps
   me identify which topic I internally have to base a topic to
   house your series in.

 * If you need to base on "pu", think twice.  You will be taken
   hostage by whatever you are basing on (this is the same if
   you base on something in "next", but "pu" is for stuff of
   even more dubious merits than "next").  On the other hand,
   your new series may turn out to be the killer application for
   the feature that was earlier felt not-so-useful and help it
   (and your series) merged to "next".