Re: Draft of Git Rev News edition 5

[Eric Sunshine <sunshine@sunshineco.com>]

On Mon, Jul 06, 2015 at 10:54:28AM -0700, Junio C Hamano wrote:
> Eric Sunshine <sunshine@sunshineco.com> writes:
> > How about this instead: prefixing with "As originally implemented",
> > with a couple s/is/was/ thrown in...
> >
> >     As originally implemented, creation of linked-worktrees was
> >     accomplished via `git checkout --to <path> <branch>`, and cleanup
> >     of leftover administrative files, after `<path>` is deleted, was
> >     done with `git prune --worktrees`. However, a recent unrelated
> >     change to `git prune` led to a discussion that concluded that
> >     worktree-related maintenance functionality didn't belong in `git
> >     prune`.
> >
> > Is that sufficient to clue in the reader that "checkout --to" is not
> > final form,...
> 
> Yeah, I think that is a good way to address my concern.
> 
> The current draft release notes to 2.5 mentions this feature as
> experimental and warns that its UI is bound to change.  We will
> ship the upcoming release with "checkout --to" and the more places
> we advise the users that this UI is not final, the better.

Here it is in patch form. (I wouldn't be surprised if the non-ASCII
characters in Duy's name in the context line get botched again...)

---- 8< ----
From: Eric Sunshine <sunshine@sunshineco.com>
Subject: [PATCH] rn-5: make it clear that "git checkout --to" is not final
 form

We don't want to mislead reader who is only lightly skimming the text
or who doesn't read the entire article that "git checkout --to" is the
final form.
---
 rev_news/drafts/edition-5.md | 11 ++++++-----
 1 file changed, 6 insertions(+), 5 deletions(-)

diff --git a/rev_news/drafts/edition-5.md b/rev_news/drafts/edition-5.md
index 241e9df..b71c99c 100644
--- a/rev_news/drafts/edition-5.md
+++ b/rev_news/drafts/edition-5.md
@@ -35,12 +35,13 @@ Unix-only and somewhat fragile `contrib/git-new-workdir` script,
 linked-worktrees recently migrated to the *master* branch, but is not
 yet part of any release.
 
-Creation of linked-worktrees is accomplished via `git checkout --to <path>
-<branch>`, and cleanup of leftover administrative files, after `<path>` is
-deleted, is done with `git prune --worktrees`. However, a recent unrelated
-change to `git prune` led to a
+As originally implemented, creation of linked-worktrees was accomplished
+via `git checkout --to <path> <branch>`, and cleanup of leftover
+administrative files after manual deletion of `<path>` was done with `git
+prune --worktrees`. However, a recent unrelated change to `git prune` led
+to a
 [discussion](http://thread.gmane.org/gmane.comp.version-control.git/272447/focus=272546)
-that concluded that worktree-related maintenance functionality doesn't
+that concluded that worktree-related maintenance functionality didn't
 belong in `git prune`.
 
 Consequently, Nguyễn Thái Ngọc Duy submitted a
-- 
2.5.0.rc1.197.g417e668