[RFC] CommitTemplate (was Re: [ANN bzr-vim] syntax and ftplugin for bzr_log.* files)

[Aaron Bentley]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Adeodato Simó wrote:
> ------------------------------------------------------------------------
> 
> # Bazaar revision bundle v0.8
> #
> # message:
> #   bzrlib/commit_template.py:
> #     - New file.

Our convention is that the first line of the commit message is a
summary, and frequently the only line displayed.
"bzrlib/commit_template.py:" does not make a good summary.

> @@ -0,0 +1,85 @@
> +# Copyright (C) 2006 by Canonical Ltd
> +
> +# This program is free software; you can redistribute it and/or modify

We have stopped using blank lines for vertical spacing in copyright
statements.  This should be:

@@ -0,0 +1,85 @@
+# Copyright (C) 2006 by Canonical Ltd
+#
+# This program is free software; you can redistribute it and/or modify

Feel free to fix up whatever file you copied it from.

I'm not really in favour of the commit template concept.  I think it
would be better if we had options that controlled what appeared, because
I think it's more likely that people would want to mix and match
different options than change the formatting related to existing options.

Under this system, a commit comment that showed pending merges would
require a new template.  And a commit comment that showed pending merges
*and* a diff would be another.  And a commit comment that showed pending
merges, and a diff against the common ancestor of the last-revision and
the rightmost parent would be another, and so on.

>  
>      def run(self, message=None, file=None, verbose=True, selected_list=None,
> -            unchanged=False, strict=False, local=False):
> +            unchanged=False, strict=False, template=None, local=False):

We don't change the order of parameters on public methods, unless
absolutely necessary.  Say it was being called like this:

    cmd.run("mymessage", file, verbose, selected_list, unchanged,
strict, local)

Your change would break that usage.

> -def edit_commit_message(infotext, ignoreline=DEFAULT_IGNORE_LINE):
> +_marker = object()
> +
> +def edit_commit_message(commit_template, ignoreline=_marker):

...

> +            if not isinstance(commit_template, c_t.CommitTemplate):
> +                # assume previous API (string)

We use symbol_versioning.DEPRECATED_PARAMETER for this purpose, and we
emit deprecation warnings when it's used.

In order to be accepted, a patch like this would need to introduce tests
for all the new code.

Aaron
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.1 (GNU/Linux)
Comment: Using GnuPG with Thunderbird - http://enigmail.mozdev.org

iD8DBQFEyhGi0F+nu1YWqI0RAhYvAJwNY94GJUg0kuBGkepKq4xFn3urtwCfTrMM
tLg/7ot9FwsoxLPairaf1YQ=
=41K3
-----END PGP SIGNATURE-----