[dna-dev] Re: @author tags in our codebase
Randall Hauch
rhauch at redhat.com
Thu Jan 15 17:04:17 EST 2009
You have a good point that automation would be improved. I agree that
automation is always better than manual work. And this is one reason
why I think the @authors tags are not good, since they often do NOT
reflect who worked on the file. SVN has the true record.
In the case of the AUTHORS file, I''m not sure automation is really
worth the effort. As we all know, becoming a committer is not an
automatic process, so this is one more thing that the project lead has
to do. (There are just a few anyway... I'm usually not the
bottleneck. :-)
So future distributions will have the AUTHORS list, and of course SVN
will have it. But there's also Ohloh, which automatically produces
the list of committers as well as a timeline of each person's
commits. See https://www.ohloh.net/p/dna/contributors.
Best regards,
Randall
On Jan 15, 2009, at 3:45 PM, Sergey Litsenko wrote:
> Let me clarify - it's not precludes efforts. I'm just saying that it
> is optional - if author tag exists - fine, if not - fine too.
> I'm not completely against removal of author tags - I'm just seeing
> it from diferent prospective - in case it's needed to get full list
> of contributors - we may automate that process of getting list of
> contributors - without restricting these tags - thats all.
> Sergiy
> From: John Verhaeg <jverhaeg at redhat.com>
> To: Sergey Litsenko <litsenko_sergey at yahoo.com>
> Cc: dna-dev at lists.jboss.org
> Sent: Friday, 16 January, 2009 4:29:27 AM
> Subject: Re: [dna-dev] Re: @author tags in our codebase
>
> 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
>
> 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/c53cd157/attachment.html
More information about the dna-dev
mailing list