Hello Allen, The intent is not for this rule to override other compatibility rules, such as the important CLI output rule. It's also not intended to give us free reign to change existing toString() implementations without due diligence. If a patch changes an existing toString() implementation that already goes out to the shell or any other form of external serialization, then the patch needs to be declined. (I concur that relying on toString() like this should never be done, and I'd encourage us to fix any occurrences we find.)
Instead, the intent is to advertise to Java API consumers that toString() output may evolve freely, and therefore we recommend against writing Java code that depends on that output format. HDFS-9732 is a good example of how to handle this. I didn't explicitly -1 it, but I did call out the CLI compatibility problem and recommend how to change the patch so that it preserves compatibility. Does this help address your concerns, or is the full code audit the only thing that would convince you to lift your -1? --Chris Nauroth On 5/12/16, 11:55 AM, "Allen Wittenauer" <allenwittena...@yahoo.com.INVALID> wrote: > > >-1 without an audit of every toString usage. We have recent examples >(e.g., HDFS-9732) where toString was used for output from CLI utilities. >(which, IMO, should never have been done, but it¹s too late now...) >Output of CLI utilities is most definitely covered by the compatibility >guidelines. Therefore, changing toString output indiscriminately may >lead to compatibility breaks. > > > >> On May 12, 2016, at 10:23 AM, Sangjin Lee <sj...@apache.org> wrote: >> >> +1. >> >> Thanks, >> Sangjin >> >> On Thu, May 12, 2016 at 10:05 AM, Ravi Prakash <ravihad...@gmail.com> >>wrote: >> >>> Thanks sounds reasonable Colin. +1 to not using toString() as an API >>> >>> On Thu, May 12, 2016 at 9:57 AM, Chris Nauroth >>><cnaur...@hortonworks.com> >>> wrote: >>> >>>> I'm in favor of making a statement in the compatibility guidelines >>>>that >>>> there is no guarantee of stability or backwards-compatibility for >>>> toString() output. If a proposed patch introduces new dependencies >>>>on a >>>> stable toString() output, such as for UI display or object >>>>serialization, >>>> then I'd consider -1'ing it and instead asking that the logic move to >>>>a >>>> different method that can provide that guarantee, i.e. >>>>toStableString(). >>>> There are further comments justifying this on HADOOP-13028 and >>>>HDFS-9732. >>>> >>>> --Chris Nauroth >>>> >>>> >>>> >>>> >>>> On 5/12/16, 9:32 AM, "Colin McCabe" <cmcc...@apache.org> wrote: >>>> >>>>> Hi all, >>>>> >>>>> Recently a discussion came up on HADOOP-13028 about the wisdom of >>>>> overloading S3AInputStream#toString to output statistics information. >>>>> It's a difficult judgement for me to make, since I'm not aware of any >>>>> compatibility guidelines for InputStream#toString. Do we have >>>>> compatibility guidelines for toString functions? >>>>> >>>>> It seems like the output of toString functions is usually used as a >>>>> debugging aid, rather than as a stable format suitable for UI >>>>>display or >>>>> object serialization. Clearly, there are a few cases where we might >>>>> want to specifically declare that a toString method is a stable API. >>>>> However, I think if we attempt to treat the toString output of all >>>>> public classes as stable, we will have greatly increased the API >>>>> surface. Should we formalize this and declare that toString >>>>>functions >>>>> are @Unstable, Evolving unless declared otherwise? >>>>> >>>>> best, >>>>> Colin >>>>> >>>>> --------------------------------------------------------------------- >>>>> To unsubscribe, e-mail: common-dev-unsubscr...@hadoop.apache.org >>>>> For additional commands, e-mail: common-dev-h...@hadoop.apache.org >>>>> >>>>> >>>> >>>> >>>> --------------------------------------------------------------------- >>>> To unsubscribe, e-mail: common-dev-unsubscr...@hadoop.apache.org >>>> For additional commands, e-mail: common-dev-h...@hadoop.apache.org >>>> >>>> >>> > > >--------------------------------------------------------------------- >To unsubscribe, e-mail: common-dev-unsubscr...@hadoop.apache.org >For additional commands, e-mail: common-dev-h...@hadoop.apache.org > > --------------------------------------------------------------------- To unsubscribe, e-mail: common-dev-unsubscr...@hadoop.apache.org For additional commands, e-mail: common-dev-h...@hadoop.apache.org
