cloudstack-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Noah Slater <nsla...@tumbolia.org>
Subject Re: [DOC] Updating Author List File
Date Tue, 09 Oct 2012 19:48:12 GMT
It might be a nice idea to maintain a THANKS file at the root of the
project, and/or a contributors page on the website or wiki. The docs can
call out to this, as a link. But then we have one place to maintain it.
You're right, it can be a motivating factor to see your name in the
official product, but this applies to code as much as it applies to
documentation. We actually have it set up so that our THANKS file on
CouchDB is automatically generated from Git, using Author and
Signed-Off-By, etc. Let me know if you want more information about that.

On Tue, Oct 9, 2012 at 8:40 PM, Brett Porter <brett@apache.org> wrote:

>
> On 10/10/2012, at 6:11 AM, Jessica Tomechak <jessica.tomechak@gmail.com>
> wrote:
>
> >>> While I get the idea, isn't the documentation something that comes
> >>> from the Apache Software Foundation? (Remember the CLA?)
> >>>
> >>> As a group we are contributing to the project as a group, the
> >>> CloudStack brings out a new release, not the individual members.
> >>>
> >>> So I'm not sure that we should mention the individual contributors to
> >>> the documentation, I don't think so.
> >>>
> >>> Wido
> >>
> >>
> >> Exactly - we've already removed many names from source code and docs.
> >> While we appreciate individuals work it does become unmaintainable over
> >> time, and we are doing this as a community working together.
> >> Radhika you do have a file named Author_Group - and you'll notice
> (unless
> >> someone has recently changed things) that the author is "Apache
> CloudStack".
> >>
> >> If you need to track who contributed it, our revision control system
> has a
> >> wonderful functionality called 'git blame' which is far more accurate
> than
> >> an authors file will ever be.
> >>
> >> Plus there is a policy against this, see:
> >> https://www.apache.org/dev/apply-license.html#contributor-copyright
> >>
> >> --David
> >>
> >
> > David,
> > It doesn't look to me as if that policy applies. We're not adding
> > individual copyrights, just a "thank you for contributing"
> acknowledgment.
> > I'm all in favor of the idea of giving doc contributors some public
> > applause for their efforts. As Radhika said, it's mainly intended to
> > encourage further contribution.
> >
> > I don't worry too much about the issue of maintaining an accurate
> > Acknowledgments list in the future. Anyone who needs an exhaustive view
> of
> > the contributors should look in the commit log, as others have noted.
> > Radhika is suggesting something more informal.
> >
> > If we don't want to change the Author_List, meaning we want to keep the
> > official doc author as "Apache CloudStack," then we could add some
> language
> > to the abstract or some other intro text. Either an "Acknowledgments"
> > section, or just "We'd like to thank the following documentation
> > contributors for their help on version 4.0 of this documentation: ..." .
>
>
> You're right that the policy referred to doesn't apply in this case.
> Additionally, the @author tags are discouraged because it gives a sense of
> individual ownership of a part of a codebase, rather than the whole
> community. The same would apply if individual docs had author markup, but a
> general list of contributors is probably fine - if everyone wants to
> maintain it. The important thing is to be consistent - across the project,
> and over time. I don't know how the author group file renders to know
> whether that is an appropriate way to capture it, but if you want to go
> down this path you might be better off having a general thanks page for all
> of CloudStack, not a doc. specific one.
>
> - Brett
>
>
> --
> Brett Porter
> brett@apache.org
> http://brettporter.wordpress.com/
> http://au.linkedin.com/in/brettporter
> http://twitter.com/brettporter
>
>
>
>
>
>


-- 
NS

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message