[dna-dev] Re: @author tags in our codebase
John Verhaeg
jverhaeg at redhat.com
Thu Jan 15 12:29:27 EST 2009
I'm not completely sold on this, but I don't really have much of an argument against it either, beyond worrying that potential contributors might not feel they're getting "enough" attribution without the direct tie-in between the source and their names. Not sure if I understand Sergey's comments about accepting contributor efforts - how does this preclude those efforts? Other than that, I'd give a +1.
John Verhaeg
Red Hat, Inc.
(314) 336-2950
----- "Sergey Litsenko" <litsenko_sergey at yahoo.com> wrote:
|
|
| -1
| It is optional - would be better to allow keeping authors tags while automating process of getting full list.
|
| On one hand, I'm not sold on the idea that if the author tag will be removed it might help to brought more commiters. If I see some issue in the source code and I know how to fix it - I'll provide a patch/fix whetever I'm in the "magic list" or not.
|
| The only question that might be asked: are OSS team members interested in accepting such contributor's efforts or not?
| It's about mentality and maturity of committers as well as part of OSS project's culture established by team members - e.g. responding to user questions, issues, etc - in e-mails, users forums, etc and welcoming user's opinions on how things should work (functional requirements). Also you can use something like following: "@author DNA Expert Group" for classes/packages designed / developed by group of authors.
|
| Generally, I believe that everything that is part of Java Language specification (e.g.) and/or part of general practices is valid and justified to be part of any source code.
|
| On the other hand, since it's possible to automate process of getting list of autors from both - SCM repository and source code/POM - maintenance would not be that hard , and IMO efforts should go that way rather than removing tags. I bet that I can find some maven plugin or develop my own to automate that process. For example, http://www.statsvn.org and http://stat-scm.sourceforge.net are good starting points.
|
| I will vote "+2" on the ability to automate process of getting full list of contributors (maven report plugin) and makit it part of distribution and Maven project site .
|
| Sergiy
|
|
|
From: "dna-dev-request at lists.jboss.org" <dna-dev-request at lists.jboss.org>
| To: dna-dev at lists.jboss.org
| Sent: Wednesday, 14 January, 2009 6:43:27 PM
| Subject: dna-dev Digest, Vol 10, Issue 5
|
| Send dna-dev mailing list submissions to
| dna-dev at lists.jboss.org
|
| To subscribe or unsubscribe via the World Wide Web, visit
| https://lists.jboss.org/mailman/listinfo/dna-dev
| or, via email, send a message with subject or body 'help' to
| dna-dev-request at lists.jboss.org
|
| You can reach the person managing the list at
| dna-dev-owner at lists.jboss.org
|
| When replying, please edit your Subject line so it is more specific
| than "Re: Contents of dna-dev digest..."
|
|
| Today's Topics:
|
| 1. Re: @author tags in our codebase (Randall Hauch)
| 2. Re: @author tags in our codebase (Vatsal)
|
|
| ----------------------------------------------------------------------
|
| Message: 1
| Date: Tue, 13 Jan 2009 16:03:23 -0600
| From: Randall Hauch < rhauch at redhat.com >
| Subject: Re: [dna-dev] @author tags in our codebase
| To: JBoss DNA < dna-dev at lists.jboss.org >
| Message-ID: < 160467FE-4D64-4943-BBAC-3D9535FD670C at redhat.com >
| Content-Type: text/plain; charset="us-ascii"
|
| We never really came to a consensus on this question, and I'd like to
| try to do that. To be clear, here is the proposal:
|
| 1) Remove the @author lines from the code, and instead rely upon SVN
| as the official master record of individual contributions
| 2) Change the Eclipse preference files to remove the @author lines
| from the code templates
| 3) Add a AUTHORS file to the distribution(s); this file will contain
| the names and email addresses for all contributors, and can even allow
| a contributor to describe their contribution if they so desire.
| 4) Change the headers to remove the "@author" wording and to replace
| it with "See the AUTHORS file in the
| distribution for a full listing of individual contributors."
| 5) Change the POM files to include the AUTHORS file in each
| distribution.
|
| The AUTHORS file would look like this:
|
| Randall Hauch ( rhauch at redhat.com )
| John Verhaeg ( jverhaeg at redhat.com )
| Dan Florian ( dflorian at redhat.com )
| Stefano Maestri ( stefano.maestri at javalinux.it )
| Serge Pagop ( Serge.Pagop at innoq.com )
| Michael Trezzi ( michael at mathwizard.org )
| Alexandre Porcelli ( porcelli at devexp.com.br )
| Sergiy Litsenko ( litsenko_sergey at yahoo.com )
|
| Note that unlike the @author tags, this file will list all
| contributors, and the names of new contributors will be appended to
| the list by the project lead. (No names will be removed from this
| file.)
|
| I would prefer to hear from every contributor, so please respond with
| +1 if you agree with this proposal, 0 if you don't care, or -1 if you
| want to keep the @author tags. If you vehemently want to keep the
| @author tags and names in the source file, please say so.
|
| Best regards,
|
| Randall
|
| On Nov 18, 2008, at 3:33 PM, Randall Hauch wrote:
|
| >
| > On Nov 18, 2008, at 2:52 PM, Stefano Maestri wrote:
| >
| >>
| >> Randall Hauch wrote on 17/11/08 22:17:
| >>> I've recently read a suggestions for open source communities that
| >>> the
| >>> author names are removed from the content. In the case of DNA's
| >>> codebase, that would mean removing the @author tags.
| >> May I ask where?
| >
| > I knew someone was going to ask. :-) I had to go back and look, but
| > here are a few:
| > http://video.google.com/videoplay?docid=-4216011961522818645&ei=8o0YSbiFOY6qrgLC2PnLDQ&q=poisonous+people
| > http://docs.ofbiz.org/display/OFBADMIN/Coding+Conventions
| > http://subversion.tigris.org/hacking.html#other-conventions
| > http://blogs.sun.com/ahe/entry/author_tags
| >
| >>
| >>>
| >>> tags:
| >>>
| >>> 1. When there are no @author tags, then there is a far smaller
| >>> notion of ownership by the author(s). On one side of this, the
| >>> author(s) may not appreciate changes to "their" code, and on the
| >>> other side, non-authors may feel intimidated about working on
| >>> code for which they are not an author. IMO, we want to
| >>> _discourage_ ownership and _encourage_ everyone to work in any
| >>> area of the code they want.
| >>>
| >> +1...but is really @author tag intimating someone, or giving
| >> ownership
| >> to some other? Quiet frankly not for me.
| >
| > I hope it doesn't discourage people from contributing and diving in
| > wherever they want. BTW, it's quite possible that no matter what
| > our policy, some people may not like it. For example, if we were to
| > adopt a policy of NOT including @author tags, some people may refuse
| > to join the community because they see the @author tag as proof they
| > worked on it. It takes all kinds of people. :-)
| >
| >>
| >> Anyway I agree on the _discurage_ownership and _encourage_everyone to
| >> work in any area, so if it can help, remove @author tag.
| >>
| >>> 1. @author tags can be inaccurate. SVN has the true history of who
| >>> contributed exactly what code.
| >>>
| >> +1
| >
| > IMO, this is perhaps the biggest justifiable reason. Its rubbish if
| > its not up-to-date, so it seems far better to not have @author tags.
| >
| >>
| >>>
| >>> The only benefit I can think of is that the @author tag does help to
| >>> give some notion of who is the "expert" of the class, in case they
| >>> need to be consulted. However, I don't believe this is really
| >>> much of
| >>> a reason, since it's far better to consult the SVN history and see
| >>> who
| >>> actually modified the different parts of the code. In fact, the
| >>> annotated views in Fisheye even show on many of the lines the name
| >>> of
| >>> the last person to change it. For example,
| >>> see http://fisheye.jboss.org/browse/DNA/trunk/dna-common/src/main/java/org/jboss/dna/common/i18n/I18n.java?r=120
| >>>
| >> abosolutely better to use fisheye...if fine people of JBoss.org would
| >> also mind to upgrade it to a more recent version it would be even
| >> better. Also Jira integration may help a lot.
| >>
| >> I would just add that if we decide to remove the tag we have to
| >> change
| >> also the license information at the beginnig of any file which say:
| >> /* 2
| >> < http://fisheye.jboss.org/browse/DNA/trunk/dna-graph/src/main/java/org/jboss/dna/graph/GraphI18n.java?r=598#l2
| >> >
| >> * JBoss, Home of Professional Open Source. 3
| >> < http://fisheye.jboss.org/browse/DNA/trunk/dna-graph/src/main/java/org/jboss/dna/graph/GraphI18n.java?r=598#l3
| >> >
| >> * Copyright 2008, Red Hat Middleware LLC, and individual
| >> contributors 4
| >> < http://fisheye.jboss.org/browse/DNA/trunk/dna-graph/src/main/java/org/jboss/dna/graph/GraphI18n.java?r=598#l4
| >> >
| >> * as indicated by the @author tags. See the copyright.txt file in
| >> the 5
| >> < http://fisheye.jboss.org/browse/DNA/trunk/dna-graph/src/main/java/org/jboss/dna/graph/GraphI18n.java?r=598#l5
| >> >
| >> * distribution for a full listing of individual contributors.
| >>
| >
| > Yes, we'd have to update the headers.
| >
| > Best regards,
| >
| > Randall
| >
|
| -------------- next part --------------
| An HTML attachment was scrubbed...
| URL: http://lists.jboss.org/pipermail/dna-dev/attachments/20090113/d2486bd9/attachment-0001.html
|
| ------------------------------
|
| Message: 2
| Date: Wed, 14 Jan 2009 13:13:23 +0530
| From: Vatsal < vatsal.avasthi at gmail.com >
| Subject: Re: [dna-dev] @author tags in our codebase
| To: dna-dev at lists.jboss.org
| Message-ID:
| < c82836c60901132343w54b690a9ha9c183e5ee61d019 at mail.gmail.com >
| Content-Type: text/plain; charset="iso-8859-1"
|
| Sometimes it is fun to see your name in author tag of a project at a later
| date when the project has matured but my vote would be for Randall's
| suggestions due to practical & maintenance reasons discussed earlier, so a
| +1 from me for this proposal(though I am not a contributor yet :) )...
| - Vatsal
|
| On Wed, Jan 14, 2009 at 3:33 AM, Randall Hauch < rhauch at redhat.com > wrote:
|
| > We never really came to a consensus on this question, and I'd like to try
| > to do that. To be clear, here is the proposal:
| >
| > 1) Remove the @author lines from the code, and instead rely upon SVN as the
| > official master record of individual contributions
| > 2) Change the Eclipse preference files to remove the @author lines from the
| > code templates
| > 3) Add a AUTHORS file to the distribution(s); this file will contain the
| > names and email addresses for all contributors, and can even allow a
| > contributor to describe their contribution if they so desire.
| > 4) Change the headers to remove the "@author" wording and to replace it
| > with "See the AUTHORS file in the
| > distribution for a full listing of individual contributors."
| > 5) Change the POM files to include the AUTHORS file in each distribution.
| >
| > The AUTHORS file would look like this:
| >
| > Randall Hauch ( rhauch at redhat.com )
| >
| > John Verhaeg ( jverhaeg at redhat.com )
| > Dan Florian ( dflorian at redhat.com )
| > Stefano Maestri ( stefano.maestri at javalinux.it )
| > Serge Pagop ( Serge.Pagop at innoq.com )
| > Michael Trezzi ( michael at mathwizard.org )
| > Alexandre Porcelli ( porcelli at devexp.com.br )
| > Sergiy Litsenko ( litsenko_sergey at yahoo.com )
| >
| >
| > Note that unlike the @author tags, this file will list all contributors,
| > and the names of new contributors will be appended to the list by the
| > project lead. (No names will be removed from this file.)
| >
| > I would prefer to hear from every contributor, so please respond with +1 if
| > you agree with this proposal, 0 if you don't care, or -1 if you want to keep
| > the @author tags. If you vehemently want to keep the @author tags and names
| > in the source file, please say so.
| >
| > Best regards,
| >
| > Randall
| >
| > On Nov 18, 2008, at 3:33 PM, Randall Hauch wrote:
| >
| >
| > On Nov 18, 2008, at 2:52 PM, Stefano Maestri wrote:
| >
| >
| > Randall Hauch wrote on 17/11/08 22:17:
| >
| > I've recently read a suggestions for open source communities that the
| >
| > author names are removed from the content. In the case of DNA's
| >
| > codebase, that would mean removing the @author tags.
| >
| > May I ask where?
| >
| >
| > I knew someone was going to ask. :-) I had to go back and look, but here
| > are a few:
| >
| > http://video.google.com/videoplay?docid=-4216011961522818645&ei=8o0YSbiFOY6qrgLC2PnLDQ&q=poisonous+people
| > http://docs.ofbiz.org/display/OFBADMIN/Coding+Conventions
| > http://subversion.tigris.org/hacking.html#other-conventions
| > http://blogs.sun.com/ahe/entry/author_tags
| >
| >
| >
| > tags:
| >
| >
| > 1. When there are no @author tags, then there is a far smaller
| >
| > notion of ownership by the author(s). On one side of this, the
| >
| > author(s) may not appreciate changes to "their" code, and on the
| >
| > other side, non-authors may feel intimidated about working on
| >
| > code for which they are not an author. IMO, we want to
| >
| > _discourage_ ownership and _encourage_ everyone to work in any
| >
| > area of the code they want.
| >
| >
| > +1...but is really @author tag intimating someone, or giving ownership
| >
| > to some other? Quiet frankly not for me.
| >
| >
| > I hope it doesn't discourage people from contributing and diving in
| > wherever they want. BTW, it's quite possible that no matter what our
| > policy, some people may not like it. For example, if we were to adopt a
| > policy of NOT including @author tags, some people may refuse to join the
| > community because they see the @author tag as proof they worked on it. It
| > takes all kinds of people. :-)
| >
| >
| > Anyway I agree on the _discurage_ownership and _encourage_everyone to
| >
| > work in any area, so if it can help, remove @author tag.
| >
| >
| > 1. @author tags can be inaccurate. SVN has the true history of who
| >
| > contributed exactly what code.
| >
| >
| > +1
| >
| >
| > IMO, this is perhaps the biggest justifiable reason. Its rubbish if its
| > not up-to-date, so it seems far better to not have @author tags.
| >
| >
| >
| > The only benefit I can think of is that the @author tag does help to
| >
| > give some notion of who is the "expert" of the class, in case they
| >
| > need to be consulted. However, I don't believe this is really much of
| >
| > a reason, since it's far better to consult the SVN history and see who
| >
| > actually modified the different parts of the code. In fact, the
| >
| > annotated views in Fisheye even show on many of the lines the name of
| >
| > the last person to change it. For example,
| >
| > see
| > http://fisheye.jboss.org/browse/DNA/trunk/dna-common/src/main/java/org/jboss/dna/common/i18n/I18n.java?r=120
| >
| >
| > abosolutely better to use fisheye...if fine people of JBoss.org would
| >
| > also mind to upgrade it to a more recent version it would be even
| >
| > better. Also Jira integration may help a lot.
| >
| >
| > I would just add that if we decide to remove the tag we have to change
| >
| > also the license information at the beginnig of any file which say:
| >
| > /* 2
| >
| > <
| > http://fisheye.jboss.org/browse/DNA/trunk/dna-graph/src/main/java/org/jboss/dna/graph/GraphI18n.java?r=598#l2
| > >
| >
| > * JBoss, Home of Professional Open Source. 3
| >
| > <
| > http://fisheye.jboss.org/browse/DNA/trunk/dna-graph/src/main/java/org/jboss/dna/graph/GraphI18n.java?r=598#l3
| > >
| >
| > * Copyright 2008, Red Hat Middleware LLC, and individual contributors 4
| >
| > <
| > http://fisheye.jboss.org/browse/DNA/trunk/dna-graph/src/main/java/org/jboss/dna/graph/GraphI18n.java?r=598#l4
| > >
| >
| > * as indicated by the @author tags. See the copyright.txt file in the 5
| >
| > <
| > http://fisheye.jboss.org/browse/DNA/trunk/dna-graph/src/main/java/org/jboss/dna/graph/GraphI18n.java?r=598#l5
| > >
| >
| > * distribution for a full listing of individual contributors.
| >
| >
| >
| > Yes, we'd have to update the headers.
| >
| > Best regards,
| >
| > Randall
| >
| >
| >
| > _______________________________________________
| > dna-dev mailing list
| > dna-dev at lists.jboss.org
| > https://lists.jboss.org/mailman/listinfo/dna-dev
| >
| >
| -------------- next part --------------
| An HTML attachment was scrubbed...
| URL: http://lists.jboss.org/pipermail/dna-dev/attachments/20090114/4b648c37/attachment.html
|
| ------------------------------
|
| _______________________________________________
| dna-dev mailing list
| dna-dev at lists.jboss.org
| https://lists.jboss.org/mailman/listinfo/dna-dev
|
|
| End of dna-dev Digest, Vol 10, Issue 5
| **************************************
|
|
Stay connected to the people that matter most with a smarter inbox. Take a look .
| _______________________________________________ dna-dev mailing list dna-dev at lists.jboss.org https://lists.jboss.org/mailman/listinfo/dna-dev
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.jboss.org/pipermail/dna-dev/attachments/20090115/c792972c/attachment.html
More information about the dna-dev
mailing list