FYI, this is how we're going to do it in HttpComponents 5: https://svn.apache.org/repos/asf/httpcomponents/httpcore/trunk/httpcore5/src/main/java/org/apache/hc/core5/annotation/ThreadingBehavior.java
Gary On Tue, Nov 29, 2016 at 2:20 PM, Gary Gregory <garydgreg...@gmail.com> wrote: > 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=cadb800f39946ec62ea2b >> 1af9fe6a2b8> >> > > >> >> > > >> <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=31ecd1f6b6d1eaf8886ac >> 902a24de418%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&link >> Code=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&link >> Code=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&link >> Code=%7B%7BlinkCode%7D%7D&tag=garygregory-20&linkId=%7B%7Bli >> nk_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 > -- 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
