[PATCH] NEWS: Document "nmbug: Translate to Python"

[PATCH] NEWS: Document "nmbug: Translate to Python"

[W. Trevor King]

This is mostly culled from the commit message for 7f2cb3be (nmbug:
Translate to Python, 2014-10-03).  I realized while writing it that
the 7f2cb3be commit message has:

  * 'nmbug log' now execs 'git log', as there's no need to keep the
    Python process around once we've launched Git there.

But we dropped that exec in favor of the subprocess approach between
v3 and v4, I just forgot to update the commit message [1].

[1]: id:e630b6763e9d0771718afee41ea15b29bb4a1de8.1409935538.git.wking@tremily.us
     http://article.gmane.org/gmane.mail.notmuch.general/19007
---
 NEWS | 48 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 48 insertions(+)

diff --git a/NEWS b/NEWS
index fa57e5d..c111dd0 100644
--- a/NEWS
+++ b/NEWS
@@ -22,6 +22,54 @@ Library changes
 Add return status to notmuch_database_close and
 notmuch_database_destroy
 
+nmbug
+-----
+
+The Perl script has been translated to Python; you'll need Python 2.7
+or anything from the 3.x line.  This gives us better control over
+subprocesses without resorting to third-party modules.  Most of the
+user-facing interface is the same, but there are a few changes, where
+reproducing the original interface was too difficult or we saw a
+change to make the underlying Git interface accessible:
+
+* 'nmbug help' has been split between the general 'nmbug --help' and
+  the command-specific 'nmbug COMMAND --help'.
+
+* Commands are no longer split into "most common", "other useful", and
+  "less common" sets.
+
+* 'nmbug commit' now only uses a single argument for the optional
+  commit-message text.
+
+* The default repository for 'nmbug push' and 'nmbug fetch' is now the
+  current branch's upstream (branch.<name>.remote) instead of
+  'origin'.  When we have to, we extract this remote by hand, but
+  where possible we just call the Git command without a repository
+  argument, and leave it to Git to figure out the default.
+
+* 'nmbug push' accepts multiple refspecs if you want to explicitly
+  specify what to push.  Otherwise, the refspec(s) pushed depend on
+  push.default.  The Perl version hardcoded 'master' as the pushed
+  refspec.
+
+* 'nmbug pull' defaults to the current branch's upstream
+  (branch.<name>.remote and branch.<name>.merge) instead of hardcoding
+  'origin' and 'master'.  It also supports multiple refspecs if for
+  some crazy reason you need an octopus merge (but mostly to avoid
+  breaking consistency with 'git pull').
+
+* 'nmbug status' now catches stderr, and doesn't print errors like:
+
+    No upstream configured for branch 'master'
+
+  The Perl implementation had just learned to avoid crashing on that
+  case, but wasn't yet catching the dying subprocess's stderr.
+
+* 'nmbug archive' now accepts positional arguments for the tree-ish
+  and additional 'git archive' options.  For example, you can run:
+
+    $ nmbug archive HEAD -- --format tar.gz
+
 nmbug-status
 ------------
 
-- 
2.1.0.60.g85f0837

Re: [PATCH] NEWS: Document "nmbug: Translate to Python"

[David Bremner]

"W. Trevor King" <wking@tremily.us> writes:

> This is mostly culled from the commit message for 7f2cb3be (nmbug:
> Translate to Python, 2014-10-03).  I realized while writing it that
> the 7f2cb3be commit message has:

This seems a bit long for a NEWS item, especially for a change that
impacts only a minority of current notmuch users. Typically even fairly
major changes (from a user point of view) have less a 10-20 line NEWS
item and refer to some external documentation.

d

Re: [PATCH] NEWS: Document "nmbug: Translate to Python"

[W. Trevor King]

[-- Attachment #1: Type: text/plain, Size: 995 bytes --]

On Tue, Oct 07, 2014 at 08:30:34AM +0200, David Bremner wrote:
> W. Trevor King writes:
> > This is mostly culled from the commit message for 7f2cb3be (nmbug:
> > Translate to Python, 2014-10-03).  I realized while writing it
> > that the 7f2cb3be commit message has:
> 
> This seems a bit long for a NEWS item, especially for a change that
> impacts only a minority of current notmuch users. Typically even
> fairly major changes (from a user point of view) have less a 10-20
> line NEWS item and refer to some external documentation.

Ok, so maybe:

  “'nmbug help' is now 'nmbug --help', and the following nmbug
  commands have slightly different interfaces: 'archive', 'commit',
  'fetch', 'log', 'pull', 'push', and 'status'.  For details on the
  new interface, run 'nmbug COMMAND --help'.”

Cheers,
Trevor

-- 
This email may be signed or encrypted with GnuPG (http://www.gnupg.org).
For more information,
see http://en.wikipedia.org/wiki/Pretty_Good_Privacy

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 819 bytes --]

Re: [PATCH] NEWS: Document "nmbug: Translate to Python"

[David Bremner]

"W. Trevor King" <wking@tremily.us> writes:

> On Tue, Oct 07, 2014 at 08:30:34AM +0200, David Bremner wrote:
>> W. Trevor King writes:
>> > This is mostly culled from the commit message for 7f2cb3be (nmbug:
>> > Translate to Python, 2014-10-03).  I realized while writing it
>> > that the 7f2cb3be commit message has:
>> 
>> This seems a bit long for a NEWS item, especially for a change that
>> impacts only a minority of current notmuch users. Typically even
>> fairly major changes (from a user point of view) have less a 10-20
>> line NEWS item and refer to some external documentation.
>
> Ok, so maybe:
>
>   “'nmbug help' is now 'nmbug --help', and the following nmbug
>   commands have slightly different interfaces: 'archive', 'commit',
>   'fetch', 'log', 'pull', 'push', and 'status'.  For details on the
>   new interface, run 'nmbug COMMAND --help'.”
>
> Cheers,
> Trevor

Yep, that sounds fine. 

Thanks!

David