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:
> > hartmannat...@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
