[svn.haxx.se] · SVN Dev · SVN Users · SVN Org · TSVN Dev · TSVN Users · Subclipse Dev · Subclipse Users · this month's index

Re: svn commit: r1807319 - in /subversion/branches/better-pristines/subversion: include/ include/private/ libsvn_client/ libsvn_wc/ svn/

From: Daniel Shahaf <d.s_at_daniel.shahaf.name>
Date: Tue, 05 Sep 2017 14:06:01 +0000

Branko Čibej wrote on Tue, 05 Sep 2017 15:56 +0200:
> On 05.09.2017 15:45, Daniel Shahaf wrote:
> > brane_at_apache.org wrote on Tue, 05 Sep 2017 07:45 +0000:
> >> Author: brane
> >> Date: Tue Sep 5 07:45:49 2017
> >> New Revision: 1807319
> >>
> >> URL: http://svn.apache.org/viewvc?rev=1807319&view=rev
> >> Log:
> >> Introduce the concept of a target format for working copy upgrades
> >> into the client library.
> >> +++ subversion/branches/better-pristines/subversion/include/svn_client.h Tue Sep 5 07:45:49 2017
> >> @@ -4201,13 +4201,34 @@ svn_client_cleanup(const char *dir,
> >> * @{
> >> */
> >>
> >> -/** Recursively upgrade a working copy from any older format to the current
> >> - * WC metadata storage format. @a wcroot_dir is the path to the WC root.
> >> +/**
> >> + * Recursively upgrade a working copy from any older format to the
> >> + * given WC metadata storage format. @a wcroot_dir is the path to the
> >> + * WC root.
> >> + *
> > Suggest to clarify that "Recursively" means into nested working copies
> > (externals), not into subdirs.
>
> Ack. Note that this is just a slightly modified copy of the original
> docstring.
>

Haven't noticed this, but the point is valid anyway :-).

> >> + * @a wc_format_version is version number of the Subversion client
> >> + * that supports a given WC metadata format; @c NULL means the newest
> >> + * supported format. Any other value must be a string representing a
> >> + * version number, e.g., "1.8" or "1.9.3". The earliest supported
> >> + * version is defined by #SVN_VERSION_SUPPORTED_WC_FORMAT.
> >> *
> > When might 1.A.3 and 1.A.4 have different formats?
>
> They might not. However, there's no reason to forbid putting the patch
> version in here. The format of this parameter is analogous to the value
> of the --compatible-version option to svnadmin. Also, using SVN_VERSION
> here should be valid. I intend the parser to just extract the first two
> dot-separated integers and ignore everything else; there's no reason to
> be too strict.
>

+1; that's exactly what I was thinking, too.

> >> * Use @a scratch_pool for any temporary allocations.
> >> *
> >> + * @since New in 1.10.
> >> + */
> >> +svn_error_t *
> >> +svn_client_upgrade2(const char *wcroot_dir,
> >> + const char* wc_format_version,
> >> + svn_client_ctx_t *ctx,
> >> + apr_pool_t *scratch_pool);
> >> +
> >> +/**
> >> + * Like svn_client_upgrade2(), but always upgrades to the newest
> >> + * supported format.
> >> + *
> >> - * @since New in 1.7.
> >> + * @deprecated Provided for backward compatibility with the 1.7 API.
> > Why drop @since? We don't usually remove @since tags when deprecating.
> > (Both here and in svn_wc_upgrade())
>
> Yes we do. I looked around and didn't find @since and @deprecated used
> together.

Counter-examples: svn_cmdline_prompt_baton_t,
svn_cmdline_create_auth_baton(), svn_txdelta_to_svndiff2().

Functions that have @deprecated but not @since are, the way we've usually
managed deprecations, supposed to be functions that were present in 1.0.
(Example: svn_txdelta_to_svndiff())

> The deprecation reason gives the original API version anyway.
>

This is just a coincidence. We could very well have "@since New in 1.1"
together with "@deprecated ... for ... the 1.9 API." if we deprecate
some old function.

Cheers,

Daniel
Received on 2017-09-05 16:06:09 CEST

This is an archived mail posted to the Subversion Dev mailing list.