On Thu, Mar 12, 2020 at 3:01 PM Daniel Shahaf <d.s_at_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.s_at_daniel.shahaf.name> wrote:
> > > hartmannathan_at_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
Received on 2020-03-13 19:37:09 CET