On Tue, Nov 29, 2016 at 1:59 PM, Benedikt Ritter <brit...@apache.org> wrote:
> I agree with Oliver. I don't think we have consensus about if and how we > want to implement this. Does it even make sense to try to document this? > What value does such a documentation have, when it is wrong 50% of the > time? I just sumed up the feedback I got from one (!) user at the > conference. I think this needs more thought. This is why I suggested to > create a PR instead of committing this directly to master. > This is a good discussion. Let's keep in mind the audience for these new annotations: - Commons Lang - All of Commons - Any Java code. Just because we may not get to document thread safety properly in Commons Lang does not mean that any other developers will fail similarly. My goal is not to decorate all of Commons Lang with these new annotations and certainly not to take on the task of documenting all of Commons ;-) I look at these annotations as a tool, a Commons way of using annotations where some folks best see fit. Providing these annotations is one thing, using them another ;-) Gary > > Regards. > Benedikt > > Gary Gregory <garydgreg...@gmail.com> schrieb am Di. 29. Nov. 2016 um > 22:33: > > > On Tue, Nov 29, 2016 at 1:12 PM, Oliver Heger < > > oliver.he...@oliver-heger.de> > > wrote: > > > > > > > > > > > Am 28.11.2016 um 22:28 schrieb Gary Gregory: > > > > WRT licensing, I re-implemented the annotations in git master. Notice > > > that > > > > all Javadocs are different and much simpler for now. Feel free to > write > > > > more. > > > > > > As the length of this thread shows, using annotations for the purpose > of > > > documenting thread-safety can be a controversial topic. > > > > > > > How is the length of a thread a reflection of its controversy? > > > > > > > I do not see the advantage over a plain text documentation in Javadoc. > > > Written text can even be more comprehensive. > > > > > > > One does not exclude the other. Annotations are easy to search. Text in > > Javadoc is subject to typos and formatting oddities that makes it much > > harder to search. > > > > Tools can work with annotations. > > > > > > > > > > The risk that the documentation goes out of sync with the > implementation > > > is given in both scenarios. But if a class announced as thread-safe is > > > manipulated in a way that it is no longer thread-safe, I would consider > > > this as a bug. This is also a kind of backwards-incompatible change. > > > > > > > That has nothing to do with annotations. If we change behavior in some > > incompatible way, that's the bug. > > > > I can interpret what you wrote as: If I remove an @Override annotation, > > then that is backwards-incompatible change. That sounds extreme. > > > > I do not think we have talked about annotations in the context of > backwards > > compatibility. Does this deserve a separate discussion? > > > > a third penny, > > Gary > > > > > > > > > > My 2 cents > > > Oliver > > > > > > > > > > > Gary > > > > > > > > On Mon, Nov 28, 2016 at 12:55 PM, Gary Gregory < > garydgreg...@gmail.com > > > > > > > wrote: > > > > > > > >> On Mon, Nov 28, 2016 at 12:18 PM, Matt Benson <gudnabr...@gmail.com > > > > > >> wrote: > > > >> > > > >>> I hoped to stay out of this. :) Points: > > > >>> > > > >>> * "provided" scope is another Maven mechanism that compiles > against a > > > >>> given dependency but does not pull the dependency in as a runtime > > > >>> dependency. I personally prefer it to marking a dependency > optional. > > > >>> * For annotations with only classfile retention, a future package > > > >>> rename e.g. lang4 would not require a consumer to upgrade just for > > the > > > >>> renamed annotation, though nothing would stop them from doing so. A > > > >>> given project could depend on either or both of lang3 and lang4 in > > any > > > >>> combination of compile-only or runtime-inclusive scope with no > > > >>> problems. > > > >>> * A standalone annotations component might be interesting, but I'm > > not > > > >>> sure if the proposed annotations constitute a critical mass > adequate > > > >>> to justify it. > > > >>> > > > >> > > > >> I would have a hard time justifying a commons-lang3-annotations > module > > > >> with only these 4 annotations. > > > >> > > > >> I could see having a Commons Annotations component though which for > > good > > > >> or bad would hold all annotations one could imagine having the > Commons > > > >> world. Hm... it smells a bit though... > > > >> > > > >> Gary > > > >> > > > >> > > > >>> > > > >>> Matt > > > >>> > > > >>> On Mon, Nov 28, 2016 at 1:21 PM, Pascal Schumacher > > > >>> <pascalschumac...@gmx.net> wrote: > > > >>>> Groovy had to change the license of its documentation from CC-A > 3.0 > > to > > > >>> the > > > >>>> Apache License during incubation: > > > >>>> > > > >>>> https://issues.apache.org/jira/browse/LEGAL-167 > > > >>>> http://markmail.org/message/2e7tehlwtpx625q4 > > > >>>> https://issues.apache.org/jira/browse/GROOVY-7470 > > > >>>> > > > >>>> So I guess Commons is probably not allowed to use these files. > > > >>>> > > > >>>> > > > >>>> Am 28.11.2016 um 18:58 schrieb Gary Gregory: > > > >>>>> > > > >>>>> On Mon, Nov 28, 2016 at 7:15 AM, Jochen Wiedmann > > > >>>>> <jochen.wiedm...@gmail.com> > > > >>>>> wrote: > > > >>>>> > > > >>>>>> On Mon, Nov 28, 2016 at 4:06 PM, sebb <seb...@gmail.com> wrote: > > > >>>>>> > > > >>>>>>> The code would not run without the JCIP jar. > > > >>>>>> > > > >>>>>> Are there licensing issues regarding that jar? > > > >>>>>> > > > >>>>> Hm, according to https://www.apache.org/legal/resolved.html, the > > > >>> license > > > >>>>> "Creative Commons Attribution (CC-A) 2.5" is discussed in the > > section > > > >>> "HOW > > > >>>>> SHOULD "WEAK COPYLEFT" LICENSES BE HANDLED?" > > > >>>>> > > > >>>>> It looks like we might have an issue but this is not clear to me > as > > > >>> IANAL. > > > >>>>> I you look at the license summary > > > >>>>> https://creativecommons.org/licenses/by/2.5/ it sure seems OK, > but > > > our > > > >>>>> resolved.html has this license on a list of licenses to watch out > > > for. > > > >>>>> > > > >>>>> So to be on the safe side, how do we best re-implement these? The > > > >>>>> annotation names we can keep as is but I would imagine that we'd > > want > > > >>> to > > > >>>>> re-write the Javadoc from scratch. > > > >>>>> > > > >>>>> Thoughts? > > > >>>>> > > > >>>>> Gary > > > >>>>> > > > >>>>> > > > >>>>>> Jochen > > > >>>>>> > > > >>>>>> > > > >>>>>> -- > > > >>>>>> The next time you hear: "Don't reinvent the wheel!" > > > >>>>>> > > > >>>>>> http://www.keystonedevelopment.co.uk/wp- > content/uploads/2014/10/ > > > >>>>>> evolution-of-the-wheel-300x85.jpg > > > >>>>>> > > > >>>>>> ------------------------------------------------------------ > > > --------- > > > >>>>>> To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org > > > >>>>>> For additional commands, e-mail: dev-h...@commons.apache.org > > > >>>>>> > > > >>>>>> > > > >>>>> > > > >>>> > > > >>>> > > > >>>> > > --------------------------------------------------------------------- > > > >>>> To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org > > > >>>> For additional commands, e-mail: dev-h...@commons.apache.org > > > >>>> > > > >>> > > > >>> ------------------------------------------------------------ > --------- > > > >>> To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org > > > >>> For additional commands, e-mail: dev-h...@commons.apache.org > > > >>> > > > >>> > > > >> > > > >> > > > >> -- > > > >> E-Mail: garydgreg...@gmail.com | ggreg...@apache.org > > > >> Java Persistence with Hibernate, Second Edition > > > >> <https://www.amazon.com/gp/product/1617290459/ref=as_li_ > > > tl?ie=UTF8&camp=1789&creative=9325&creativeASIN=1617290459& > > > linkCode=as2&tag=garygregory-20&linkId=cadb800f39946ec62ea2b1af9fe6a2 > b8> > > > >> > > > >> <http://// > > ir-na.amazon-adsystem.com/e/ir?t=garygregory-20&l=am2&o=1&a= > > > 1617290459> > > > >> JUnit in Action, Second Edition > > > >> <https://www.amazon.com/gp/product/1935182021/ref=as_li_ > > > tl?ie=UTF8&camp=1789&creative=9325&creativeASIN=1935182021& > > > > > linkCode=as2&tag=garygregory-20&linkId=31ecd1f6b6d1eaf8886ac902a24de4 > 18%22 > > > > > > > >> > > > >> <http://// > > ir-na.amazon-adsystem.com/e/ir?t=garygregory-20&l=am2&o=1&a= > > > 1935182021> > > > >> Spring Batch in Action > > > >> <https://www.amazon.com/gp/product/1935182951/ref=as_li_ > > > tl?ie=UTF8&camp=1789&creative=9325&creativeASIN=1935182951& > > > linkCode=%7B%7BlinkCode%7D%7D&tag=garygregory-20&linkId=%7B% > > > 7Blink_id%7D%7D%22%3ESpring+Batch+in+Action> > > > >> <http://// > > ir-na.amazon-adsystem.com/e/ir?t=garygregory-20&l=am2&o=1&a= > > > 1935182951> > > > >> Blog: http://garygregory.wordpress.com > > > >> Home: http://garygregory.com/ > > > >> Tweet! http://twitter.com/GaryGregory > > > >> > > > > > > > > > > > > > > > > > > --------------------------------------------------------------------- > > > To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org > > > For additional commands, e-mail: dev-h...@commons.apache.org > > > > > > > > > > > > -- > > E-Mail: garydgreg...@gmail.com | ggreg...@apache.org > > Java Persistence with Hibernate, Second Edition > > < > > https://www.amazon.com/gp/product/1617290459/ref=as_li_ > tl?ie=UTF8&camp=1789&creative=9325&creativeASIN=1617290459& > linkCode=as2&tag=garygregory-20&linkId=cadb800f39946ec62ea2b1af9fe6a2b8 > > > > > > > <http://// > > ir-na.amazon-adsystem.com/e/ir?t=garygregory-20&l=am2&o=1&a=1617290459> > > JUnit in Action, Second Edition > > < > > https://www.amazon.com/gp/product/1935182021/ref=as_li_ > tl?ie=UTF8&camp=1789&creative=9325&creativeASIN=1935182021& > linkCode=as2&tag=garygregory-20&linkId=31ecd1f6b6d1eaf8886ac902a24de418%22 > > > > > > > <http://// > > ir-na.amazon-adsystem.com/e/ir?t=garygregory-20&l=am2&o=1&a=1935182021> > > Spring Batch in Action > > < > > https://www.amazon.com/gp/product/1935182951/ref=as_li_ > tl?ie=UTF8&camp=1789&creative=9325&creativeASIN=1935182951& > linkCode=%7B%7BlinkCode%7D%7D&tag=garygregory-20&linkId=%7B% > 7Blink_id%7D%7D%22%3ESpring+Batch+in+Action > > > > > <http://// > > ir-na.amazon-adsystem.com/e/ir?t=garygregory-20&l=am2&o=1&a=1935182951> > > Blog: http://garygregory.wordpress.com > > Home: http://garygregory.com/ > > Tweet! http://twitter.com/GaryGregory > > > -- E-Mail: garydgreg...@gmail.com | ggreg...@apache.org Java Persistence with Hibernate, Second Edition <https://www.amazon.com/gp/product/1617290459/ref=as_li_tl?ie=UTF8&camp=1789&creative=9325&creativeASIN=1617290459&linkCode=as2&tag=garygregory-20&linkId=cadb800f39946ec62ea2b1af9fe6a2b8> <http:////ir-na.amazon-adsystem.com/e/ir?t=garygregory-20&l=am2&o=1&a=1617290459> JUnit in Action, Second Edition <https://www.amazon.com/gp/product/1935182021/ref=as_li_tl?ie=UTF8&camp=1789&creative=9325&creativeASIN=1935182021&linkCode=as2&tag=garygregory-20&linkId=31ecd1f6b6d1eaf8886ac902a24de418%22> <http:////ir-na.amazon-adsystem.com/e/ir?t=garygregory-20&l=am2&o=1&a=1935182021> Spring Batch in Action <https://www.amazon.com/gp/product/1935182951/ref=as_li_tl?ie=UTF8&camp=1789&creative=9325&creativeASIN=1935182951&linkCode=%7B%7BlinkCode%7D%7D&tag=garygregory-20&linkId=%7B%7Blink_id%7D%7D%22%3ESpring+Batch+in+Action> <http:////ir-na.amazon-adsystem.com/e/ir?t=garygregory-20&l=am2&o=1&a=1935182951> Blog: http://garygregory.wordpress.com Home: http://garygregory.com/ Tweet! http://twitter.com/GaryGregory
