You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@harmony.apache.org by "Geir Magnusson Jr." <ge...@apache.org> on 2005/10/02 06:10:48 UTC
[project policy] Author credit and attribution
Might as well do this, now that we are getting in code by the bucketful.
One of the fundamental notions of an Apache project is the notion of
community ownership - that this is _our_ project, collectively.
However, this collective project is composed of significant
individual contributions, contributions which we want to recognize.
So the problem we have to solve is how to balance these two ideas.
The Apache Board has recommended that projects not employ author tags
in their source code. The main motivation for this recommendation is
to remove "territorial ownership" from code.
I've worked in projects that did it, and some that didn't. When tags
were there, I think it gave people a chance to 'sign' their work, and
I'll be the first to admit that when I did my first-ever commit that
had my name on it, I was proud! It's a natural thing to be proud of
our work. The flip side was that I've seen it lead to people
believing they "own" a piece of code because of the tags, I've seen
"keeping up with the joneses" where every contributor adds an author
tag, no matter what, leading to strange feelings about what is the
level that makes on an "author".... For example, reformatting w/
eclipse?
When we started Geronimo, we decided to not use author tags, and
we've never looked back - it just didn't matter.
Now, if you look around the foundation codebases, there are author
tags historically, and some projects just chose to ignore the
recommendation and use them.
My preference is to not have them here in Apache Harmony, but that
said, I want to make sure that contributors are recognized for both
general participation as well as significant 'bulk' contributions.
To solve that, I can think of two things offhand :
1) We should have a page like the HTTP project (you know, the "Apache
webserver")
http://httpd.apache.org/contributors/
where we have a list of our committers and their ongoing activities,
and a section noting the contributions that the project accepted.
2) In order to get attribution closer to the code, we could also have
an "AUTHORS" file per module, so that we'd easily know who is working
on what - if you are a committer working on a module, you'd add your
name to the list. Additionally, if there was a bulk contribution
that seeded a module (like the three contribs we have now), we can
have a note about that at the top of the AUTHORS file such as
"ArchieVM originally contributed by Archie Cobbs" (yeah, I know we
aren't calling it ArchieVM...) or something like that.
Thoughts?
geir
--
Geir Magnusson Jr +1-203-665-6437
geirm@apache.org
Re: [project policy] Author credit and attribution
Posted by "Geir Magnusson Jr." <ge...@apache.org>.
On Oct 2, 2005, at 6:49 PM, Leo Simons wrote:
> On Sun, Oct 02, 2005 at 12:04:55PM +0200, Mark Wielaard wrote:
>
[SNIP]
> Cool!
>
> I also like
>
> http://subversion.tigris.org/hacking.html
>
> which is basically the same kind of guide, only a little different
> in some
> corners. At apache, lots of projects have subtly (or not so subtly)
> different
> ways of doing things, for example HTTPD has this:
>
> http://httpd.apache.org/dev/guidelines.html
>
And please don't forget
http://incubator.apache.org/harmony/guidelines.html
They need tuning, but I think an excellent start ;)
geir
--
Geir Magnusson Jr +1-203-665-6437
geirm@apache.org
Re: [project policy] Author credit and attribution
Posted by Leo Simons <ma...@leosimons.com>.
On Sun, Oct 02, 2005 at 12:04:55PM +0200, Mark Wielaard wrote:
> If you are looking for some guidelines for working together on code and
> how to keep track of who wrote what when then I would recommend starting
> out with our GNU Classpath Hacker Guide. Specifically chapter 7.
> "Working on the code, Working with others". It explains that the main
> rule is to always explain and discuss everything on the patches
> mailinglists. No commit is made before it has been posted first.
> http://www.gnu.org/software/classpath/docs/hacking.html#SEC8
Cool!
I also like
http://subversion.tigris.org/hacking.html
which is basically the same kind of guide, only a little different in some
corners. At apache, lots of projects have subtly (or not so subtly) different
ways of doing things, for example HTTPD has this:
http://httpd.apache.org/dev/guidelines.html
whereas for example Apache Gump sometimes sees a rather sizeable codebase
overhaul without prior discussion. Both are fun and healthy projects, and
both do things the "apache way". Just differently ;)
In particular, I like to believe that the "lazy consensus" concept around
the ASF is nice -- it means that, sometimes, if you're relatively confident
that everyone agrees with the changes you're about to make, you just make
the change, and then when the commit notification scrolls by, if it turns
out someone didn't agree, they reply, and explain why not, and you back out
the change. Eg "commit then review", so you do commit stuff before posting
it to the mailing list.
But only when confident that the change is "non-controversial". And then we
try and err on the safe side.
We'll see how it goes.
LSD
Re: [project policy] Author credit and attribution
Posted by "Geir Magnusson Jr." <ge...@apache.org>.
Thanks mark for this link. This captures a lot about how I like to
work. Some key things :
"The main thing is to always discuss what you are up to on the
mailinglist. Making sure that everybody knows who is working on what
is the most important thing to make sure we cooperate most
effectively." (aka "Don't be a cowboy" :)
We also have the 'adding anything non-trivial that you didn't write
yourself' pretty well covered with our bulk contribution policy.
We will certainly steal this :
"Commits for completely unrelated changes they should be committed
separately"
as it's good to remind people of this.
And will emphasize maintaining the changelog. One solution to that
is to let JIRA generate your change list, but that presumes that any
work people do is logged in a JIRA. I think JIRA is a great tool,
but I also hope to avoid people having technical discussion in JIRA
comments, which sometimes happens...
More inline :
On Oct 2, 2005, at 6:04 AM, Mark Wielaard wrote:
> Hi,
>
> If you are looking for some guidelines for working together on code
> and
> how to keep track of who wrote what when then I would recommend
> starting
> out with our GNU Classpath Hacker Guide. Specifically chapter 7.
> "Working on the code, Working with others". It explains that the main
> rule is to always explain and discuss everything on the patches
> mailinglists. No commit is made before it has been posted first.
> http://www.gnu.org/software/classpath/docs/hacking.html#SEC8
>
> Just following that main rule makes sure that everybody knows what and
> why things happen.
I think that for now, going with commit then review removes synch
points that we should be getting anyway with community monitoring of
the svn diff stream in email. I know that has worked very well,
allowing people to work (with "always discuss what you are up to" as
a prereq) and having the patch discussed only if someone throws an
exception. That said, I do believe that with big patches, or tricky
things, it's best that the author discuss first, but this seems to be
"you know it when you see it".
> Next there are all kinds of practical guidelines such
> as maintaining a clear and concise ChangeLog for every commit.
> Splitting
> commits for unrelated code changes, or changes to code and changes to
> formatting, etc for clarity. And when to ask for permission to
> commit a
> change. Also important is to always use the same code style guide (see
> chapter 6) so that the code looks like it is part of a whole.
Agreed.
>
> There is currently no strict rule about "author tags". Some people add
> them some don't. This isn't really a problem. The ChangeLog file
> documents in very precise detail who really wrote what (and of course
> CVS has a similar record if you happen to be online). And there is a
> AUTHORS file listing all active hackers and a THANKS file for
> documenting who else helped out with bug reports, hints or moral
> support. Also the release announcements always include a full list of
> all contributors and a summary of their contributions.
>
> Currently there are about 80 committers creating around 15 patches a
> day. And the Hacker Guide really helps to keep some structure to the
> project without being so strict that it makes contributing difficult.
>
The key is to keep the rails greased and remove roadblocks to
everyday work... That's why (this point anyway) I'm so in favor of
commit then [lazily] review.
geir
--
Geir Magnusson Jr +1-203-665-6437
geirm@apache.org
Re: [project policy] Author credit and attribution
Posted by Mark Wielaard <ma...@klomp.org>.
Hi,
If you are looking for some guidelines for working together on code and
how to keep track of who wrote what when then I would recommend starting
out with our GNU Classpath Hacker Guide. Specifically chapter 7.
"Working on the code, Working with others". It explains that the main
rule is to always explain and discuss everything on the patches
mailinglists. No commit is made before it has been posted first.
http://www.gnu.org/software/classpath/docs/hacking.html#SEC8
Just following that main rule makes sure that everybody knows what and
why things happen. Next there are all kinds of practical guidelines such
as maintaining a clear and concise ChangeLog for every commit. Splitting
commits for unrelated code changes, or changes to code and changes to
formatting, etc for clarity. And when to ask for permission to commit a
change. Also important is to always use the same code style guide (see
chapter 6) so that the code looks like it is part of a whole.
There is currently no strict rule about "author tags". Some people add
them some don't. This isn't really a problem. The ChangeLog file
documents in very precise detail who really wrote what (and of course
CVS has a similar record if you happen to be online). And there is a
AUTHORS file listing all active hackers and a THANKS file for
documenting who else helped out with bug reports, hints or moral
support. Also the release announcements always include a full list of
all contributors and a summary of their contributions.
Currently there are about 80 committers creating around 15 patches a
day. And the Hacker Guide really helps to keep some structure to the
project without being so strict that it makes contributing difficult.
Cheers,
Mark
Re: [project policy] Author credit and attribution
Posted by "Geir Magnusson Jr." <ge...@apache.org>.
On Oct 2, 2005, at 12:22 AM, acoliver@apache.org wrote:
> I prefer them. I've never had any of the problems that happened in
> Avalon or other projects in any project I've been involved in.
> Author tags do not signify ownership, they signify "I wuz here".
> They are also a principle reason that a lot of newbies get involved
> in open source because they can point potential employers to look
> at code that they wrote (I know a few of this).
>
Sure, but not having an author tag doesn't take that away. I really
like them for newbies, but I also have no empirical evidence that
people contribute more eagerly with an author tag...
> They also make it WAY more convienient to say "Hey andy why did you
> do this dumb thing here?" rather than have to figure out who did
> that dumb thing.
Author tags don't actually solve that either when there are more than
one author. You still have to go look at the log.
>
> I do recommend omitting email addresses as those just help spammers
> and tend to create useless name change commits.
>
> I'm also the most guilty offender of forgetting to include my
> @author tag on projects that require it :-)
>
They are very seductive, but I think can be a negative in the long term.
Being aggressive on recognizing the contributions on the contributor
page and AUTHOR files should balance the somewhat debatable theory
about newbies.
geir
> -Andy
>
>
> Geir Magnusson Jr. wrote:
>
>> Might as well do this, now that we are getting in code by the
>> bucketful.
>> One of the fundamental notions of an Apache project is the notion
>> of community ownership - that this is _our_ project,
>> collectively. However, this collective project is composed of
>> significant individual contributions, contributions which we want
>> to recognize. So the problem we have to solve is how to balance
>> these two ideas.
>> The Apache Board has recommended that projects not employ author
>> tags in their source code. The main motivation for this
>> recommendation is to remove "territorial ownership" from code.
>> I've worked in projects that did it, and some that didn't. When
>> tags were there, I think it gave people a chance to 'sign' their
>> work, and I'll be the first to admit that when I did my first-
>> ever commit that had my name on it, I was proud! It's a natural
>> thing to be proud of our work. The flip side was that I've seen
>> it lead to people believing they "own" a piece of code because of
>> the tags, I've seen "keeping up with the joneses" where every
>> contributor adds an author tag, no matter what, leading to
>> strange feelings about what is the level that makes on an
>> "author".... For example, reformatting w/ eclipse?
>> When we started Geronimo, we decided to not use author tags, and
>> we've never looked back - it just didn't matter.
>> Now, if you look around the foundation codebases, there are
>> author tags historically, and some projects just chose to ignore
>> the recommendation and use them.
>> My preference is to not have them here in Apache Harmony, but
>> that said, I want to make sure that contributors are recognized
>> for both general participation as well as significant 'bulk'
>> contributions. To solve that, I can think of two things offhand :
>> 1) We should have a page like the HTTP project (you know, the
>> "Apache webserver")
>> http://httpd.apache.org/contributors/
>> where we have a list of our committers and their ongoing
>> activities, and a section noting the contributions that the
>> project accepted.
>> 2) In order to get attribution closer to the code, we could also
>> have an "AUTHORS" file per module, so that we'd easily know who
>> is working on what - if you are a committer working on a module,
>> you'd add your name to the list. Additionally, if there was a
>> bulk contribution that seeded a module (like the three contribs
>> we have now), we can have a note about that at the top of the
>> AUTHORS file such as "ArchieVM originally contributed by Archie
>> Cobbs" (yeah, I know we aren't calling it ArchieVM...) or
>> something like that.
>> Thoughts?
>> geir
>>
>
>
> --
> Andrew C. Oliver
> SuperLink Software, Inc.
>
> Java to Excel using POI
> http://www.superlinksoftware.com/services/poi
> Commercial support including features added/implemented, bugs fixed.
>
>
--
Geir Magnusson Jr +1-203-665-6437
geirm@apache.org
Re: [project policy] Author credit and attribution
Posted by ac...@apache.org.
I prefer them. I've never had any of the problems that happened in
Avalon or other projects in any project I've been involved in. Author
tags do not signify ownership, they signify "I wuz here". They are also
a principle reason that a lot of newbies get involved in open source
because they can point potential employers to look at code that they
wrote (I know a few of this).
They also make it WAY more convienient to say "Hey andy why did you do
this dumb thing here?" rather than have to figure out who did that dumb
thing.
I do recommend omitting email addresses as those just help spammers and
tend to create useless name change commits.
I'm also the most guilty offender of forgetting to include my @author
tag on projects that require it :-)
-Andy
Geir Magnusson Jr. wrote:
> Might as well do this, now that we are getting in code by the bucketful.
>
> One of the fundamental notions of an Apache project is the notion of
> community ownership - that this is _our_ project, collectively.
> However, this collective project is composed of significant individual
> contributions, contributions which we want to recognize. So the
> problem we have to solve is how to balance these two ideas.
>
> The Apache Board has recommended that projects not employ author tags
> in their source code. The main motivation for this recommendation is
> to remove "territorial ownership" from code.
>
> I've worked in projects that did it, and some that didn't. When tags
> were there, I think it gave people a chance to 'sign' their work, and
> I'll be the first to admit that when I did my first-ever commit that
> had my name on it, I was proud! It's a natural thing to be proud of
> our work. The flip side was that I've seen it lead to people believing
> they "own" a piece of code because of the tags, I've seen "keeping up
> with the joneses" where every contributor adds an author tag, no matter
> what, leading to strange feelings about what is the level that makes on
> an "author".... For example, reformatting w/ eclipse?
>
> When we started Geronimo, we decided to not use author tags, and we've
> never looked back - it just didn't matter.
>
> Now, if you look around the foundation codebases, there are author tags
> historically, and some projects just chose to ignore the recommendation
> and use them.
>
> My preference is to not have them here in Apache Harmony, but that
> said, I want to make sure that contributors are recognized for both
> general participation as well as significant 'bulk' contributions. To
> solve that, I can think of two things offhand :
>
> 1) We should have a page like the HTTP project (you know, the "Apache
> webserver")
>
> http://httpd.apache.org/contributors/
>
> where we have a list of our committers and their ongoing activities,
> and a section noting the contributions that the project accepted.
>
> 2) In order to get attribution closer to the code, we could also have
> an "AUTHORS" file per module, so that we'd easily know who is working
> on what - if you are a committer working on a module, you'd add your
> name to the list. Additionally, if there was a bulk contribution that
> seeded a module (like the three contribs we have now), we can have a
> note about that at the top of the AUTHORS file such as "ArchieVM
> originally contributed by Archie Cobbs" (yeah, I know we aren't
> calling it ArchieVM...) or something like that.
>
> Thoughts?
>
> geir
>
>
--
Andrew C. Oliver
SuperLink Software, Inc.
Java to Excel using POI
http://www.superlinksoftware.com/services/poi
Commercial support including features added/implemented, bugs fixed.
Re: [project policy] Author credit and attribution
Posted by Stefano Mazzocchi <st...@apache.org>.
Leo Simons wrote:
> I'm against author tags. I've had too many discussion about it in
> the past that I don't want to repeat though, so I won't bother ;)
Same here.
SVN + a detailed credits.txt file is a much better way to deal with this
issue and it scales for years, not just for the little ego massage of
the moment.
--
Stefano.
Re: [project policy] Author credit and attribution
Posted by Leo Simons <ma...@leosimons.com>.
I'm against author tags. I've had too many discussion about it in
the past that I don't want to repeat though, so I won't bother ;)
- LSD
Re: [project policy] Author credit and attribution
Posted by Archie Cobbs <ar...@dellroad.org>.
Geir Magnusson Jr. wrote:
> The Apache Board has recommended that projects not employ author tags
> in their source code. The main motivation for this recommendation is
> to remove "territorial ownership" from code.
My vote is to not have @author tags. The SVN log should be the definitive
source of authorship information. Besides, who's the @author when 15
different people have committed changes? They quickly become out of date.
Just my (one) opinion of course.
-Archie
__________________________________________________________________________
Archie Cobbs * CTO, Awarix * http://www.awarix.com