You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@subversion.apache.org by ha...@apache.org on 2020/03/12 15:15:43 UTC
svn commit: r1875127 - /subversion/site/publish/docs/release-notes/1.14.html
Author: hartmannathan
Date: Thu Mar 12 15:15:43 2020
New Revision: 1875127
URL: http://svn.apache.org/viewvc?rev=1875127&view=rev
Log:
1.14 release notes: Document selectable shelving implementation
* docs/release-notes/1.14.html
(shelving): Document that users can select between Shelving-v2 and
Shelving-v3 via the SVN_EXPERIMENTAL_COMMANDS environment
variable, as introduced in r1875037.
Modified:
subversion/site/publish/docs/release-notes/1.14.html
Modified: subversion/site/publish/docs/release-notes/1.14.html
URL: http://svn.apache.org/viewvc/subversion/site/publish/docs/release-notes/1.14.html?rev=1875127&r1=1875126&r2=1875127&view=diff
==============================================================================
--- subversion/site/publish/docs/release-notes/1.14.html (original)
+++ subversion/site/publish/docs/release-notes/1.14.html Thu Mar 12 15:15:43 2020
@@ -575,11 +575,9 @@ not use, but which introduces more I/O w
title="Link to this section">¶</a>
</h4>
-<p>This change was first introduced in 1.11.</p>
-
<p>Shelving (<a href="https://issues.apache.org/jira/browse/SVN-3625">issue
-#3625</a>), first introduced in Subversion 1.10, is improved to handle more
-kinds of changes more robustly.</p>
+#3625</a>), first introduced in Subversion 1.10, has been developed further to
+handle more kinds of changes more robustly.</p>
<div class="notice">
<p><span style="color: red"><b>WARNING:</b></span> The shelving feature is
@@ -587,19 +585,47 @@ kinds of changes more robustly.</p>
while development continues. It is expected to change significantly during
and after the 1.14.x series. There is no promise of backward compatibility
while it remains experimental.</p>
+
+ <p>Shelving in 1.14 is incompatible with shelves created by 1.10. See
+ <a href="#shelving-transition">the transition notes</a> on recovering 1.10
+ shelves and differences in commands.</p>
</div>
-<div class="notice">
- <p>While the shelving feature in 1.14 can handle more kinds of changes than
- that in 1.10, some users have reported that it performs much more slowly,
- especially when used with large working copies.</p>
-</div>
+<p>Subversion 1.14 offers two different shelving CLI implementations,
+selectable by an environment variable (see
+<a href="http://svn.apache.org/r1875037">r1875037</a>.) These are
+"Shelving-v2" as introduced in 1.11, and "Shelving-v3" as introduced in 1.12.
+The two implementations are incompatible with each other, but both are offered
+because they have substantially different pros and cons.</p>
+
+<p>The shelving CLI implementation is selected by an environment variable,
+<tt>SVN_EXPERIMENTAL_COMMANDS</tt>, as follows:</p>
+
+<table border="1">
+ <tr>
+ <th>environment variable</th>
+ <th>shelving CLI implementation</th>
+ </tr>
+ <tr>
+ <td>Environment variable not set</td>
+ <td>Shelving-v3, as introduced in 1.12</td>
+ </tr>
+ <tr>
+ <td><tt>SVN_EXPERIMENTAL_COMMANDS=shelf3</tt></td>
+ <td>Shelving-v3, as introduced in 1.12</td>
+ </tr>
+ <tr>
+ <td><tt>SVN_EXPERIMENTAL_COMMANDS=shelf2</tt></td>
+ <td>Shelving-v2, as introduced in 1.11</td>
+ </tr>
+ <tr>
+ <td><tt>SVN_EXPERIMENTAL_COMMANDS=</tt></td>
+ <td>No shelving CLI</td>
+ </tr>
+</table>
-<p>Shelving in 1.14 is incompatible with shelves created by 1.10. See
-<a href="#shelving-transition">the transition notes</a> on recovering 1.10
-shelves and differences in commands.</p>
-
-<p>The main improvements and changes are:</p>
+<p>Shelving-v2, first introduced in 1.11, improves upon the initial shelving
+feature introduced in 1.10. The main improvements and changes are:</p>
<ul>
<li>checkpointing support: a shelf stores multiple versions of a
change; shelving adds a new version to the named shelf; you can
@@ -617,13 +643,59 @@ shelves and differences in commands.</p>
WC has been modified (e.g. updated) since the shelf was saved</li>
</ul>
-<p>The kinds of change you can shelve are committable changes to files and
-properties, except the following kinds which are not yet supported:</p>
+<p>Shelving-v2 can shelve committable changes to files and properties, except
+the following kinds which it does not support:</p>
<ul>
<li>copies and moves</li>
<li>creating and deleting directories</li>
</ul>
+<p>Shelving-v3, first introduced in 1.12, can handle more kinds of changes
+than Shelving-v2. In particular, it supports shelving of all committable
+changes. However, it performs much more slowly than Shelving-v2 and uses more
+disk space, especially when used with large working copies.</p>
+
+<p>The following table summarizes the kinds of changes that can be shelved by
+the two implementations:</p>
+
+<table border="1">
+ <tr>
+ <th>WC State or Change</th>
+ <th>Shelving-v2</th>
+ <th>Shelving-v3</th>
+ </tr>
+ <tr>
+ <td>file text, file delete/add, most properties</td>
+ <td>yes</td>
+ <td>yes</td>
+ </tr>
+ <tr>
+ <td>mergeinfo changes</td>
+ <td>yes</td>
+ <td>yes</td>
+ </tr>
+ <tr>
+ <td>copies and moves</td>
+ <td>no</td>
+ <td>as copies<sup>1</sup></td>
+ </tr>
+ <tr>
+ <td>directories (mkdir/rmdir/...)</td>
+ <td>no</td>
+ <td>yes</td>
+ </tr>
+ <tr>
+ <td>binary files & properties</td>
+ <td>yes</td>
+ <td>yes</td>
+ </tr>
+ <tr>
+ <td colspan="3"><sup>1</sup>On shelving, a move is converted to
+ copy-and-delete, just like it is on commit.
+ </td>
+ </tr>
+</table>
+
<p>Shelving commands (see their help for details):</p>
<ul>
<li><tt>svn x-shelf-diff</tt></li>
Re: svn commit: r1875127 -
/subversion/site/publish/docs/release-notes/1.14.html
Posted by Daniel Shahaf <d....@daniel.shahaf.name>.
Julian Foad wrote on Sat, 14 Mar 2020 14:28 +0000:
> Thank you Nathan and Daniel for working on the 'shelving' part of the
> release notes.
>
> Please ping me when you've done what you can, and I'll review and/or fix
> as best I can.
>
> Thanks,
> - Julian
You're welcome. I don't have any pending work, so consider yourself
pinged by me. However, AFAIK Nathan plans to implement some of my
proposals from the grandparent post.
Cheers,
Daniel
Re: svn commit: r1875127 -
/subversion/site/publish/docs/release-notes/1.14.html
Posted by Julian Foad <ju...@apache.org>.
Thank you Nathan and Daniel for working on the 'shelving' part of the
release notes.
Please ping me when you've done what you can, and I'll review and/or fix
as best I can.
Thanks,
- Julian
Re: svn commit: r1875127 -
/subversion/site/publish/docs/release-notes/1.14.html
Posted by Daniel Shahaf <d....@daniel.shahaf.name>.
Nathan Hartman wrote on Fri, 13 Mar 2020 14:36 -0400:
> On Thu, Mar 12, 2020 at 3:01 PM Daniel Shahaf <d....@daniel.shahaf.name> wrote:
> > - Promote #shelving from h4 to h3
> > - Transform #checkpoint to an #h4 inside #shelving
> > - Reword #shelving-transition to be more explicitly only about
> > "upgrading existing shelves from 1.10/1.11/1.12/1.13 to 1.14"
> > and clearly pointing to #shelving for details about the feature
> > — for example:
> > + Change the subsection's title to "Upgrading 1.10–1.13 shelves to 1.14"
> > + Add an emphasized first sentence similar to the italicized "This
> > article is about the political concept of subversion. For other
> > uses, see [Subversion (disambiguation)]." on
> > https://en.wikipedia.org/wiki/Subversion.
> > - (bikeshed) Rename the anchor #shelving-transition to something that
> > doesn't begin with "#shelving-", since #foo-bar is usually a
> > subsection of #foo
>
> This sounds quite sensible. Thanks for the suggestions. I will try to
> do this within the next couple of days.
Thanks, Nathan!
Re: svn commit: r1875127 - /subversion/site/publish/docs/release-notes/1.14.html
Posted by Nathan Hartman <ha...@gmail.com>.
On Thu, Mar 12, 2020 at 3:01 PM Daniel Shahaf <d....@daniel.shahaf.name> wrote:
> Nathan Hartman wrote on Thu, 12 Mar 2020 18:15 +00:00:
> > On Thu, Mar 12, 2020 at 12:36 PM Daniel Shahaf
> > <d....@daniel.shahaf.name> wrote:
> > > hartmannathan@apache.org wrote on Thu, 12 Mar 2020 15:15 -0000:
> > > > 1.14 release notes: Document selectable shelving implementation
> > > >
> > > > * docs/release-notes/1.14.html (shelving): Document that users can
> > > > select between Shelving-v2 and Shelving-v3 via the
> > > > SVN_EXPERIMENTAL_COMMANDS environment variable, as introduced
> > > > in r1875037.
> > >
> > > Shelving is now mentioned in three separate sections: #shelving-
> > > transition, #checkpointing, #shelving. I am a little disoriented by
> > > this. Shouldn't #shelving-transition link to #shelving, for one?
> >
> > Yes, it's clumsy. I suppose that #checkpointing could be combined with
> > #shelving, since it's really part of the same feature.
> >
> > I don't know what to do about #shelving-transition, though, because it
> > belongs in "Compatibility Concerns," while the other information
> > belongs in "Enhancements and Bug Fixes" -> "Command Line Client
> > Improvements."
>
> How about:
>
> - Promote #shelving from h4 to h3
> - Transform #checkpoint to an #h4 inside #shelving
> - Reword #shelving-transition to be more explicitly only about
> "upgrading existing shelves from 1.10/1.11/1.12/1.13 to 1.14"
> and clearly pointing to #shelving for details about the feature
> — for example:
> + Change the subsection's title to "Upgrading 1.10–1.13 shelves to 1.14"
> + Add an emphasized first sentence similar to the italicized "This
> article is about the political concept of subversion. For other
> uses, see [Subversion (disambiguation)]." on
> https://en.wikipedia.org/wiki/Subversion.
> - (bikeshed) Rename the anchor #shelving-transition to something that
> doesn't begin with "#shelving-", since #foo-bar is usually a
> subsection of #foo
This sounds quite sensible. Thanks for the suggestions. I will try to
do this within the next couple of days.
Cheers,
Nathan
Re: svn commit: r1875127 - /subversion/site/publish/docs/release-notes/1.14.html
Posted by Nathan Hartman <ha...@gmail.com>.
On Sun, Mar 15, 2020 at 6:24 PM Daniel Shahaf <d....@daniel.shahaf.name> wrote:
> > To make it so, in r1875216 I've added a top-level Experimental Features
> > section, moved all experimental stuff there, and in particular, made a pretty
> > significant refactoring of all the shelving text.
>
> LGTM, thanks!
Thanks for reviewing it, and so quickly.
More below...
> > r1875217 improves the look of the end of the document, where we had a bunch
> > of h2 sections in rapid succession, none of which contained very much text.
> > My ulterior motive here is to make Enthusiastic Contributors Welcome a bit
> > more visible. :-)
> >
> > Feedback welcome.
>
> Not related to your changes, but it'd be nice if the mentions of #svn
> and #svn-dev were links, either to irc://chat.freenode.net/ (what's the
> URI scheme for IRC/SSL?) or to webchat.freenode.net. We have multiple
> examples of both elsewhere on the site.
>
> In fact, all those places would benefit from spelling out the "Don't ask
> permission to ask your question" and "After asking, wait for an answer"
> aspects of IRC. It might be worthwhile be nice to have a canonical
> landing place — e.g., a section on /mailing-lists.html — that both gives
> the links and explains these expectations, and then have all other links
> point to that one rather than directly to *.freenode.net.
>
> Though of course that's no longer about 1.14…
I think Julian suggested something like this previously and it has
been in the back of my mind for the eventual website reboot. I like
the idea of a consolidated "contact us" type page, including mailing
lists and IRC. In the meantime, yes, the IRC info could be added to
/mailing-lists.html without too much trouble.
This reminds me: On /mailing-lists.html, we have links to gmane. AFAIK
that's long gone, so probably those should be removed.
I'll try to free up some cycles for that...
Nathan
Re: svn commit: r1875127 - /subversion/site/publish/docs/release-notes/1.14.html
Posted by Daniel Shahaf <d....@daniel.shahaf.name>.
Nathan Hartman wrote on Sun, 15 Mar 2020 22:08 +00:00:
> On Thu, Mar 12, 2020 at 3:01 PM Daniel Shahaf <d....@daniel.shahaf.name> wrote:
> > Nathan Hartman wrote on Thu, 12 Mar 2020 18:15 +00:00:
> > > On Thu, Mar 12, 2020 at 12:36 PM Daniel Shahaf
> > > <d....@daniel.shahaf.name> wrote:
> > > > Shelving is now mentioned in three separate sections: #shelving-
> > > > transition, #checkpointing, #shelving. I am a little disoriented by
> > > > this. Shouldn't #shelving-transition link to #shelving, for one?
>
> (snip)
>
> > - Promote #shelving from h4 to h3
> > - Transform #checkpoint to an #h4 inside #shelving
> > - Reword #shelving-transition to be more explicitly only about
> > "upgrading existing shelves from 1.10/1.11/1.12/1.13 to 1.14"
> > and clearly pointing to #shelving for details about the feature
> > — for example:
> > + Change the subsection's title to "Upgrading 1.10–1.13 shelves to 1.14"
> > + Add an emphasized first sentence similar to the italicized "This
> > article is about the political concept of subversion. For other
> > uses, see [Subversion (disambiguation)]." on
> > https://en.wikipedia.org/wiki/Subversion.
> > - (bikeshed) Rename the anchor #shelving-transition to something that
> > doesn't begin with "#shelving-", since #foo-bar is usually a
> > subsection of #foo
>
> As Daniel points out, shelving was mentioned in three different places. More
> generally, we had information about experimental stuff scattered all
> throughout the release notes. I didn't like that because not only does it
> reduce readability, but it makes it seem as though every other thing is
> experimental and incomplete, when in fact, most of Subversion is very stable.
>
> As I started working to incorporate Daniel's suggestions vis a vis shelving,
> it occurred to me that to solve the above problem, and in keeping with the
> theme of stability and accessibility, we should consolidate ALL experimental
> text into one section.
>
> To make it so, in r1875216 I've added a top-level Experimental Features
> section, moved all experimental stuff there, and in particular, made a pretty
> significant refactoring of all the shelving text.
LGTM, thanks!
> r1875217 improves the look of the end of the document, where we had a bunch
> of h2 sections in rapid succession, none of which contained very much text.
> My ulterior motive here is to make Enthusiastic Contributors Welcome a bit
> more visible. :-)
>
> Feedback welcome.
Not related to your changes, but it'd be nice if the mentions of #svn
and #svn-dev were links, either to irc://chat.freenode.net/ (what's the
URI scheme for IRC/SSL?) or to webchat.freenode.net. We have multiple
examples of both elsewhere on the site.
In fact, all those places would benefit from spelling out the "Don't ask
permission to ask your question" and "After asking, wait for an answer"
aspects of IRC. It might be worthwhile be nice to have a canonical
landing place — e.g., a section on /mailing-lists.html — that both gives
the links and explains these expectations, and then have all other links
point to that one rather than directly to *.freenode.net.
Though of course that's no longer about 1.14…
Cheers,
Daniel
Re: svn commit: r1875127 - /subversion/site/publish/docs/release-notes/1.14.html
Posted by Nathan Hartman <ha...@gmail.com>.
On Thu, Mar 12, 2020 at 3:01 PM Daniel Shahaf <d....@daniel.shahaf.name> wrote:
> Nathan Hartman wrote on Thu, 12 Mar 2020 18:15 +00:00:
> > On Thu, Mar 12, 2020 at 12:36 PM Daniel Shahaf
> > <d....@daniel.shahaf.name> wrote:
> > > Shelving is now mentioned in three separate sections: #shelving-
> > > transition, #checkpointing, #shelving. I am a little disoriented by
> > > this. Shouldn't #shelving-transition link to #shelving, for one?
(snip)
> - Promote #shelving from h4 to h3
> - Transform #checkpoint to an #h4 inside #shelving
> - Reword #shelving-transition to be more explicitly only about
> "upgrading existing shelves from 1.10/1.11/1.12/1.13 to 1.14"
> and clearly pointing to #shelving for details about the feature
> — for example:
> + Change the subsection's title to "Upgrading 1.10–1.13 shelves to 1.14"
> + Add an emphasized first sentence similar to the italicized "This
> article is about the political concept of subversion. For other
> uses, see [Subversion (disambiguation)]." on
> https://en.wikipedia.org/wiki/Subversion.
> - (bikeshed) Rename the anchor #shelving-transition to something that
> doesn't begin with "#shelving-", since #foo-bar is usually a
> subsection of #foo
As Daniel points out, shelving was mentioned in three different places. More
generally, we had information about experimental stuff scattered all
throughout the release notes. I didn't like that because not only does it
reduce readability, but it makes it seem as though every other thing is
experimental and incomplete, when in fact, most of Subversion is very stable.
As I started working to incorporate Daniel's suggestions vis a vis shelving,
it occurred to me that to solve the above problem, and in keeping with the
theme of stability and accessibility, we should consolidate ALL experimental
text into one section.
To make it so, in r1875216 I've added a top-level Experimental Features
section, moved all experimental stuff there, and in particular, made a pretty
significant refactoring of all the shelving text.
r1875217 improves the look of the end of the document, where we had a bunch
of h2 sections in rapid succession, none of which contained very much text.
My ulterior motive here is to make Enthusiastic Contributors Welcome a bit
more visible. :-)
Feedback welcome.
Cheers,
Nathan
Re: svn commit: r1875127 - /subversion/site/publish/docs/release-notes/1.14.html
Posted by Daniel Shahaf <d....@daniel.shahaf.name>.
Nathan Hartman wrote on Thu, 12 Mar 2020 18:15 +00:00:
> On Thu, Mar 12, 2020 at 12:36 PM Daniel Shahaf
> <d....@daniel.shahaf.name> wrote:
> > hartmannathan@apache.org wrote on Thu, 12 Mar 2020 15:15 -0000:
> > > 1.14 release notes: Document selectable shelving implementation
> > >
> > > * docs/release-notes/1.14.html (shelving): Document that users can
> > > select between Shelving-v2 and Shelving-v3 via the
> > > SVN_EXPERIMENTAL_COMMANDS environment variable, as introduced
> > > in r1875037.
> >
> > Shelving is now mentioned in three separate sections: #shelving-
> > transition, #checkpointing, #shelving. I am a little disoriented by
> > this. Shouldn't #shelving-transition link to #shelving, for one?
>
> Yes, it's clumsy. I suppose that #checkpointing could be combined with
> #shelving, since it's really part of the same feature.
>
> I don't know what to do about #shelving-transition, though, because it
> belongs in "Compatibility Concerns," while the other information
> belongs in "Enhancements and Bug Fixes" -> "Command Line Client
> Improvements."
How about:
- Promote #shelving from h4 to h3
- Transform #checkpoint to an #h4 inside #shelving
- Reword #shelving-transition to be more explicitly only about
"upgrading existing shelves from 1.10/1.11/1.12/1.13 to 1.14"
and clearly pointing to #shelving for details about the feature
— for example:
+ Change the subsection's title to "Upgrading 1.10–1.13 shelves to 1.14"
+ Add an emphasized first sentence similar to the italicized "This
article is about the political concept of subversion. For other
uses, see [Subversion (disambiguation)]." on
https://en.wikipedia.org/wiki/Subversion.
- (bikeshed) Rename the anchor #shelving-transition to something that
doesn't begin with "#shelving-", since #foo-bar is usually a
subsection of #foo
Cheers,
Daniel
Re: svn commit: r1875127 - /subversion/site/publish/docs/release-notes/1.14.html
Posted by Nathan Hartman <ha...@gmail.com>.
On Thu, Mar 12, 2020 at 12:36 PM Daniel Shahaf <d....@daniel.shahaf.name> wrote:
> hartmannathan@apache.org wrote on Thu, 12 Mar 2020 15:15 -0000:
> > 1.14 release notes: Document selectable shelving implementation
> >
> > * docs/release-notes/1.14.html
> > (shelving): Document that users can select between Shelving-v2 and
> > Shelving-v3 via the SVN_EXPERIMENTAL_COMMANDS environment
> > variable, as introduced in r1875037.
>
> Shelving is now mentioned in three separate sections:
> #shelving-transition, #checkpointing, #shelving. I am a little
> disoriented by this. Shouldn't #shelving-transition link to #shelving,
> for one?
Yes, it's clumsy. I suppose that #checkpointing could be combined with
#shelving, since it's really part of the same feature.
I don't know what to do about #shelving-transition, though, because it
belongs in "Compatibility Concerns," while the other information
belongs in "Enhancements and Bug Fixes" -> "Command Line Client
Improvements."
More below.
> > + <td>Environment variable not set</td>
> > + <td>Shelving-v3, as introduced in 1.12</td>
>
> This row is no longer correct as of r1875039.
Good catch. This error is fixed in r1875131.
Thanks,
Nathan
Re: svn commit: r1875127 -
/subversion/site/publish/docs/release-notes/1.14.html
Posted by Daniel Shahaf <d....@daniel.shahaf.name>.
hartmannathan@apache.org wrote on Thu, 12 Mar 2020 15:15 -0000:
> 1.14 release notes: Document selectable shelving implementation
>
> * docs/release-notes/1.14.html
> (shelving): Document that users can select between Shelving-v2 and
> Shelving-v3 via the SVN_EXPERIMENTAL_COMMANDS environment
> variable, as introduced in r1875037.
Shelving is now mentioned in three separate sections:
#shelving-transition, #checkpointing, #shelving. I am a little
disoriented by this. Shouldn't #shelving-transition link to #shelving,
for one?
> +<p>The shelving CLI implementation is selected by an environment variable,
> +<tt>SVN_EXPERIMENTAL_COMMANDS</tt>, as follows:</p>
> +
> +<table border="1">
> + <tr>
> + <th>environment variable</th>
> + <th>shelving CLI implementation</th>
> + </tr>
> + <tr>
> + <td>Environment variable not set</td>
> + <td>Shelving-v3, as introduced in 1.12</td>
This row is no longer correct as of r1875039.
> + </tr>
Cheers,
Daniel
Re: svn commit: r1875127 -
/subversion/site/publish/docs/release-notes/1.14.html
Posted by Daniel Shahaf <d....@daniel.shahaf.name>.
hartmannathan@apache.org wrote on Thu, 12 Mar 2020 15:15 -0000:
> 1.14 release notes: Document selectable shelving implementation
>
> * docs/release-notes/1.14.html
> (shelving): Document that users can select between Shelving-v2 and
> Shelving-v3 via the SVN_EXPERIMENTAL_COMMANDS environment
> variable, as introduced in r1875037.
Shelving is now mentioned in three separate sections:
#shelving-transition, #checkpointing, #shelving. I am a little
disoriented by this. Shouldn't #shelving-transition link to #shelving,
for one?
> +<p>The shelving CLI implementation is selected by an environment variable,
> +<tt>SVN_EXPERIMENTAL_COMMANDS</tt>, as follows:</p>
> +
> +<table border="1">
> + <tr>
> + <th>environment variable</th>
> + <th>shelving CLI implementation</th>
> + </tr>
> + <tr>
> + <td>Environment variable not set</td>
> + <td>Shelving-v3, as introduced in 1.12</td>
This row is no longer correct as of r1875039.
> + </tr>
Cheers,
Daniel