best practices for contributors

[Si Chen-2]

Ok, so as a follow up to the write up of guidelines for committers, I  
thought we should have some guildelines for contributors as well to  
help them work with the project.

1.  Send in a signed ICLA to Apache.

2.  Follow coding conventions.

3.  Install the OFBIZ Subversion client configuration file (where is  
this?)

4.  Discuss your features with the community.  What are you trying to  
implement, and how are you planning to do it?  This is especially  
important if you are new to the project.

5.  Write clear, well-commented and understandable code.  Don't take  
shortcuts, especially around variable names and error or warning  
messages.  Use understandable data structures.  Remember, somebody  
else will be working with your code down the road.

6.  Start out with small contributions which are easier to review.  
In the process, get familiar with the project's coding style and  
"thought process."

7.  Put your contributions on JIRA instead of emailing it directly to  
the committers, so everybody can review and comment on it.

8.  Get other members of the community to try your patch.  Write the  
users list and tell them what you've done and ask them to try it out  
and vote for it.  This would help the committers when they are  
reviewing your patches.


Si

[BJ Freeman]

It would seem, like with patents and trademarks, that once released to
the public, without those being documented first, that the work is
public and there is no license inferred.
so if someone sends a submission to the Jira, without license in the
code, and or the apache license, that in fact is public and no claims by
the author.


Si Chen sent the following on 6/27/2006 10:09 AM:

> Ok, so as a follow up to the write up of guidelines for committers, I
> thought we should have some guildelines for contributors as well to help
> them work with the project.
>
> 1.  Send in a signed ICLA to Apache.
>
> 2.  Follow coding conventions.
>
> 3.  Install the OFBIZ Subversion client configuration file (where is this?)
>
> 4.  Discuss your features with the community.  What are you trying to
> implement, and how are you planning to do it?  This is especially
> important if you are new to the project.
>
> 5.  Write clear, well-commented and understandable code.  Don't take
> shortcuts, especially around variable names and error or warning
> messages.  Use understandable data structures.  Remember, somebody else
> will be working with your code down the road.
>
> 6.  Start out with small contributions which are easier to review.  In
> the process, get familiar with the project's coding style and "thought
> process."
>
> 7.  Put your contributions on JIRA instead of emailing it directly to
> the committers, so everybody can review and comment on it.
>
> 8.  Get other members of the community to try your patch.  Write the
> users list and tell them what you've done and ask them to try it out and
> vote for it.  This would help the committers when they are reviewing
> your patches.
>
>
> Si
>
>

[Yoav Shapira-2]

Hi,
Everything Si said is cool by me, except one bullet point:

On 6/27/06, Si Chen <[hidden email]> wrote:
> Ok, so as a follow up to the write up of guidelines for committers, I
> thought we should have some guildelines for contributors as well to
> help them work with the project.
>
> 1.  Send in a signed ICLA to Apache.

Why?  This is not necessary unless one becomes a committer.  A
contributor can contribute code without an iCLA: someone else with an
iCLA must commit this code.  By contributing in a public mailing list
or attaching their patch to an ASF issue tracker, the contributor
acknowledges his or her contribution may be included in a product
licensed under the Apache License.  And in a happy world, we get and
process many such contributions.

The reason we don't want to require an iCLA from new contributors is
to not raise the bar for them: let the community grow with the lowest
possible barriers to entry.

Yoav

[cjhowe]

That line of thought is changing every day in IP law
(especially when you're not country specific) and best
to stay on the conservative side.  Submitting to
Apache JIRA makes it clear to the contributor that
they are releasing the contribution under the Apache
license, so it's really not an issue any longer.

If you take commercials for example. They are sent out
in the public everday with and without copyright
claims included, however the work is still the
ownership of the creator and you're still limited by
the terms of fair use in reusing that commercial
without their consent.

--- BJ Freeman <[hidden email]> wrote:

> It would seem, like with patents and trademarks,
> that once released to
> the public, without those being documented first,
> that the work is
> public and there is no license inferred.
> so if someone sends a submission to the Jira,
> without license in the
> code, and or the apache license, that in fact is
> public and no claims by
> the author.
>
>
> Si Chen sent the following on 6/27/2006 10:09 AM:
> > Ok, so as a follow up to the write up of
> guidelines for committers, I
> > thought we should have some guildelines for
> contributors as well to help
> > them work with the project.
> >
> > 1.  Send in a signed ICLA to Apache.
> >
> > 2.  Follow coding conventions.
> >
> > 3.  Install the OFBIZ Subversion client
> configuration file (where is this?)
> >
> > 4.  Discuss your features with the community.
> What are you trying to
> > implement, and how are you planning to do it?
> This is especially
> > important if you are new to the project.
> >
> > 5.  Write clear, well-commented and understandable
> code.  Don't take
> > shortcuts, especially around variable names and
> error or warning
> > messages.  Use understandable data structures.
> Remember, somebody else
> > will be working with your code down the road.
> >
> > 6.  Start out with small contributions which are
> easier to review.  In
> > the process, get familiar with the project's
> coding style and "thought
> > process."
> >
> > 7.  Put your contributions on JIRA instead of
> emailing it directly to
> > the committers, so everybody can review and
> comment on it.
> >
> > 8.  Get other members of the community to try your
> patch.  Write the
> > users list and tell them what you've done and ask
> them to try it out and
> > vote for it.  This would help the committers when
> they are reviewing
> > your patches.
> >
> >
> > Si
> >
> >
>

[Si Chen-2]

Ok, sorry about my mistake here!

So what about your comment that  "A publicly-documented submission  
relieves us of the need to seek an
iCLA from that individual"?

Should we ensure that new contributions are either on JIRA or posted  
somewhere publicly?  If someone sends me a patch off the list, does  
that mean that it would not qualify?

Si

On Jun 27, 2006, at 10:22 AM, Yoav Shapira wrote:

> Hi,
> Everything Si said is cool by me, except one bullet point:
>
> On 6/27/06, Si Chen <[hidden email]> wrote:
>> Ok, so as a follow up to the write up of guidelines for committers, I
>> thought we should have some guildelines for contributors as well to
>> help them work with the project.
>>
>> 1.  Send in a signed ICLA to Apache.
>
> Why?  This is not necessary unless one becomes a committer.  A
> contributor can contribute code without an iCLA: someone else with an
> iCLA must commit this code.  By contributing in a public mailing list
> or attaching their patch to an ASF issue tracker, the contributor
> acknowledges his or her contribution may be included in a product
> licensed under the Apache License.  And in a happy world, we get and
> process many such contributions.
>
> The reason we don't want to require an iCLA from new contributors is
> to not raise the bar for them: let the community grow with the lowest
> possible barriers to entry.
>
> Yoav

[Adrian Crum]

Si Chen wrote:
> 7.  Put your contributions on JIRA instead of emailing it directly to  
> the committers, so everybody can review and comment on it.

One of the side effects I like about this approach is - if the comitters don't
have time to review the code, users can still download the patches and use them
on their local copies.

Contributing to OFBiz can be confusing at times. I'll share some of my confusion
  with the hope that it will help you compose guidelines.

I've suggested ideas on the mailing lists. One or two people will express an
interest in my ideas. I started out posting my ideas on the Wiki - so everyone
can comment on them and use the Wiki as a whiteboard. I was chastised for doing
that - the Wiki is to be used for "Official OFBiz Purposes Only."

Then I tried using Jira. That seemed to go over better. There seems to be times
when Jira submissions are accepted favorably, and other times when I've been
told that I should have discussed it in the mailing lists first.

Personally, I would prefer the latter - make a suggestion on the mailing list,
and if there is any interest, discuss it further as a Jira issue. I like being
able to post patches, have people download them and leave comments, and have
them upload changes or enhancements to the patches. It can be very interactive.
If the idea goes nowhere, then just close the Jira issue.

-Adrian

[cjhowe]

I would think that an iCLA is needed because you are
making the claim that the work you are submitting is
your work.  ie, not plagerized and not owned by
someone who may be employing you.

--- Si Chen <[hidden email]> wrote:

> Ok, sorry about my mistake here!
>
> So what about your comment that  "A
> publicly-documented submission  
> relieves us of the need to seek an
> iCLA from that individual"?
>
> Should we ensure that new contributions are either
> on JIRA or posted  
> somewhere publicly?  If someone sends me a patch off
> the list, does  
> that mean that it would not qualify?
>
> Si
>
> On Jun 27, 2006, at 10:22 AM, Yoav Shapira wrote:
>
> > Hi,
> > Everything Si said is cool by me, except one
> bullet point:
> >
> > On 6/27/06, Si Chen
> <[hidden email]> wrote:
> >> Ok, so as a follow up to the write up of
> guidelines for committers, I
> >> thought we should have some guildelines for
> contributors as well to
> >> help them work with the project.
> >>
> >> 1.  Send in a signed ICLA to Apache.
> >
> > Why?  This is not necessary unless one becomes a
> committer.  A
> > contributor can contribute code without an iCLA:
> someone else with an
> > iCLA must commit this code.  By contributing in a
> public mailing list
> > or attaching their patch to an ASF issue tracker,
> the contributor
> > acknowledges his or her contribution may be
> included in a product
> > licensed under the Apache License.  And in a happy
> world, we get and
> > process many such contributions.
> >
> > The reason we don't want to require an iCLA from
> new contributors is
> > to not raise the bar for them: let the community
> grow with the lowest
> > possible barriers to entry.
> >
> > Yoav
>
>

[Jacques Le Roux]

> Hi,
> Everything Si said is cool by me, except one bullet point:
>
> On 6/27/06, Si Chen <[hidden email]> wrote:
> > Ok, so as a follow up to the write up of guidelines for committers, I
> > thought we should have some guildelines for contributors as well to
> > help them work with the project.
> >
> > 1.  Send in a signed ICLA to Apache.
>
> Why?  This is not necessary unless one becomes a committer.  A
> contributor can contribute code without an iCLA: someone else with an
> iCLA must commit this code.  By contributing in a public mailing list
> or attaching their patch to an ASF issue tracker, the contributor
> acknowledges his or her contribution may be included in a product
> licensed under the Apache License.  And in a happy world, we get and
> process many such contributions.
>
> The reason we don't want to require an iCLA from new contributors is
> to not raise the bar for them: let the community grow with the lowest
> possible barriers to entry.

So, the << Grant license to ASF for inclusion in ASF works (as per the Apache
Software License §5) >> option is enough ?

Jacques

> Yoav

[Yoav Shapira-2]

Hi,

On 6/27/06, Si Chen <[hidden email]> wrote:
> Ok, sorry about my mistake here!

No worries, no need to apologize.

> So what about your comment that  "A publicly-documented submission
> relieves us of the need to seek an
> iCLA from that individual"?
>
> Should we ensure that new contributions are either on JIRA or posted
> somewhere publicly?  If someone sends me a patch off the list, does
> that mean that it would not qualify?

That's right: in that case simply ask the poster to submit the patch
to JIRA.  You can even start a new JIRA issue for it yourself, then
just send him/her the URL and ask him/her to attach his patch to the
issue.

Yoav

[Yoav Shapira-2]

Hola,

On 6/27/06, Chris Howe <[hidden email]> wrote:
> That line of thought is changing every day in IP law
> (especially when you're not country specific) and best
> to stay on the conservative side.  Submitting to
> Apache JIRA makes it clear to the contributor that
> they are releasing the contribution under the Apache
> license, so it's really not an issue any longer.

IANAL, but I'll take your word for it.  As I said, JIRA (or whatever
issue tracker we use) is the best / preferred method, so that's
probably what should be in the contributors' guide.  The (public,
archived, date-establishing) mailing list is still better than private
emails.  And most importantly, an iCLA is not needed.

Yoav

[Yoav Shapira-2]

Hola,
I wouldn't think so.  The act of committing a patch into the ASF
repository is where the committer (not necessarily the same person as
the contributor) verifies the piece is not plagiarized.

Most projects choose to accept contributions from people without an
iCLA, and try to verify the originality of the contributions
themselves (a committer does it).  It's typically trivial stuff,
except for major additions, for which these projects do require iCLAs.
 However, if we want to shift the burden of proof (thereby drastically
raising the barrier to entry for new contributors) onto contributors,
we can ask them to file an iCLA with their first original
contribution.

All of this is qualified: IANAL.  If you're worried about this or
simply want to get an authoritative answer, subscribe to
[hidden email] and ask ;)   We'll do whatever they say.  If
what they say requires changes to
http://www.apache.org/dev/contributors.html#patches (the canonical
reference for contributors, and note it makes no iCLA requirement),
we'll need to get that key document updated as well.

Yoav

On 6/27/06, Chris Howe <[hidden email]> wrote:

> I would think that an iCLA is needed because you are
> making the claim that the work you are submitting is
> your work.  ie, not plagerized and not owned by
> someone who may be employing you.
>
> --- Si Chen <[hidden email]> wrote:
>
> > Ok, sorry about my mistake here!
> >
> > So what about your comment that  "A
> > publicly-documented submission
> > relieves us of the need to seek an
> > iCLA from that individual"?
> >
> > Should we ensure that new contributions are either
> > on JIRA or posted
> > somewhere publicly?  If someone sends me a patch off
> > the list, does
> > that mean that it would not qualify?
> >
> > Si
> >
> > On Jun 27, 2006, at 10:22 AM, Yoav Shapira wrote:
> >
> > > Hi,
> > > Everything Si said is cool by me, except one
> > bullet point:
> > >
> > > On 6/27/06, Si Chen
> > <[hidden email]> wrote:
> > >> Ok, so as a follow up to the write up of
> > guidelines for committers, I
> > >> thought we should have some guildelines for
> > contributors as well to
> > >> help them work with the project.
> > >>
> > >> 1.  Send in a signed ICLA to Apache.
> > >
> > > Why?  This is not necessary unless one becomes a
> > committer.  A
> > > contributor can contribute code without an iCLA:
> > someone else with an
> > > iCLA must commit this code.  By contributing in a
> > public mailing list
> > > or attaching their patch to an ASF issue tracker,
> > the contributor
> > > acknowledges his or her contribution may be
> > included in a product
> > > licensed under the Apache License.  And in a happy
> > world, we get and
> > > process many such contributions.
> > >
> > > The reason we don't want to require an iCLA from
> > new contributors is
> > > to not raise the bar for them: let the community
> > grow with the lowest
> > > possible barriers to entry.
> > >
> > > Yoav
> >
> >
>
>

--
Yoav Shapira
Nimalex LLC
1 Mifflin Place, Suite 310
Cambridge, MA, USA
[hidden email] / www.yoavshapira.com

[Si Chen-2]

Ok, changed.  Please let me know if it's ok now:  http://
docs.ofbiz.org/display/OFBIZ/OFBiz+Committers+Roles+and+Responsibilities

Si


On Jun 27, 2006, at 10:54 AM, Yoav Shapira wrote:

> Hi,
>
> On 6/27/06, Si Chen <[hidden email]> wrote:
>> Ok, sorry about my mistake here!
>
> No worries, no need to apologize.
>
>> So what about your comment that  "A publicly-documented submission
>> relieves us of the need to seek an
>> iCLA from that individual"?
>>
>> Should we ensure that new contributions are either on JIRA or posted
>> somewhere publicly?  If someone sends me a patch off the list, does
>> that mean that it would not qualify?
>
> That's right: in that case simply ask the poster to submit the patch
> to JIRA.  You can even start a new JIRA issue for it yourself, then
> just send him/her the URL and ask him/her to attach his patch to the
> issue.
>
> Yoav

[Yoav Shapira-2]

Hi,

> So, the << Grant license to ASF for inclusion in ASF works (as per the Apache
> Software License §5) >> option is enough ?

Yes.

Yoav

[BJ Freeman]

some what on this same point, most project have a contributors section
in the repository.
It is understood that this is not part of the main project, and is not
the responsibility of the developers of the project to keep the
contributions in sync, with the project.

The is something akin to the specialized and hot-deploy in ofbiz, IMHO.

I would like to see something along those lines addresses in the
practices as well.


Adrian Crum sent the following on 6/27/2006 10:36 AM:

> Si Chen wrote:
>> 7.  Put your contributions on JIRA instead of emailing it directly to  
>> the committers, so everybody can review and comment on it.
>
> One of the side effects I like about this approach is - if the comitters
> don't have time to review the code, users can still download the patches
> and use them on their local copies.
>
> Contributing to OFBiz can be confusing at times. I'll share some of my
> confusion  with the hope that it will help you compose guidelines.
>
> I've suggested ideas on the mailing lists. One or two people will
> express an interest in my ideas. I started out posting my ideas on the
> Wiki - so everyone can comment on them and use the Wiki as a whiteboard.
> I was chastised for doing that - the Wiki is to be used for "Official
> OFBiz Purposes Only."
>
> Then I tried using Jira. That seemed to go over better. There seems to
> be times when Jira submissions are accepted favorably, and other times
> when I've been told that I should have discussed it in the mailing lists
> first.
>
> Personally, I would prefer the latter - make a suggestion on the mailing
> list, and if there is any interest, discuss it further as a Jira issue.
> I like being able to post patches, have people download them and leave
> comments, and have them upload changes or enhancements to the patches.
> It can be very interactive. If the idea goes nowhere, then just close
> the Jira issue.
>
> -Adrian
>
>

[David E. Jones]

As general feedback on this: it would also be nice to have a distinction in the document between committers and contributors, and to make it clear that you do not need commit privileges or special privileges in any system in order to contribute, and that if you want to become a committer then start by working on various contributions. This is something I've thought about writing a number of times given various random questions from people who want to contribute to the project and are therefore requesting commit privileges and what not.

-David


Si Chen wrote:

> Ok, so as a follow up to the write up of guidelines for committers, I
> thought we should have some guildelines for contributors as well to help
> them work with the project.
>
> 1.  Send in a signed ICLA to Apache.
>
> 2.  Follow coding conventions.
>
> 3.  Install the OFBIZ Subversion client configuration file (where is this?)
>
> 4.  Discuss your features with the community.  What are you trying to
> implement, and how are you planning to do it?  This is especially
> important if you are new to the project.
>
> 5.  Write clear, well-commented and understandable code.  Don't take
> shortcuts, especially around variable names and error or warning
> messages.  Use understandable data structures.  Remember, somebody else
> will be working with your code down the road.
>
> 6.  Start out with small contributions which are easier to review.  In
> the process, get familiar with the project's coding style and "thought
> process."
>
> 7.  Put your contributions on JIRA instead of emailing it directly to
> the committers, so everybody can review and comment on it.
>
> 8.  Get other members of the community to try your patch.  Write the
> users list and tell them what you've done and ask them to try it out and
> vote for it.  This would help the committers when they are reviewing
> your patches.
>
>
> Si
>

[Si Chen-2]

Yeah, you're right.  This actually is very important.

Also I was thinking of adding Marco Risalti's suggestion about  
internationalizing code in here.  While I don't think we should make  
it a requirement that contributions should be internationalized, we  
should suggest that everybody do it as much as possible.

Ok, I'll work on creating this page later on docs.ofbiz.org

Si


On Jun 27, 2006, at 12:12 PM, David E. Jones wrote:

>
> As general feedback on this: it would also be nice to have a  
> distinction in the document between committers and contributors,  
> and to make it clear that you do not need commit privileges or  
> special privileges in any system in order to contribute, and that  
> if you want to become a committer then start by working on various  
> contributions. This is something I've thought about writing a  
> number of times given various random questions from people who want  
> to contribute to the project and are therefore requesting commit  
> privileges and what not.
>
> -David
>
>
> Si Chen wrote:
>> Ok, so as a follow up to the write up of guidelines for  
>> committers, I thought we should have some guildelines for  
>> contributors as well to help them work with the project.
>> 1.  Send in a signed ICLA to Apache.
>> 2.  Follow coding conventions.
>> 3.  Install the OFBIZ Subversion client configuration file (where  
>> is this?)
>> 4.  Discuss your features with the community.  What are you trying  
>> to implement, and how are you planning to do it?  This is  
>> especially important if you are new to the project.
>> 5.  Write clear, well-commented and understandable code.  Don't  
>> take shortcuts, especially around variable names and error or  
>> warning messages.  Use understandable data structures.  Remember,  
>> somebody else will be working with your code down the road.
>> 6.  Start out with small contributions which are easier to  
>> review.  In the process, get familiar with the project's coding  
>> style and "thought process."
>> 7.  Put your contributions on JIRA instead of emailing it directly  
>> to the committers, so everybody can review and comment on it.
>> 8.  Get other members of the community to try your patch.  Write  
>> the users list and tell them what you've done and ask them to try  
>> it out and vote for it.  This would help the committers when they  
>> are reviewing your patches.
>> Si

[David E. Jones]

Si Chen wrote:
> Yeah, you're right.  This actually is very important.
>
> Also I was thinking of adding Marco Risalti's suggestion about
> internationalizing code in here.  While I don't think we should make it
> a requirement that contributions should be internationalized, we should
> suggest that everybody do it as much as possible.

Yes, that's a good point. We should certainly encourage i18n of new code even if we don't require it.

-David

[BJ Freeman]

I agree, with the Jira in place, that is the default commit for
contributors.
More what I was saying was there would be a place for the contributors
code to be that could be accessed, but not thru the official code section.
so the code in Specialized would be moved to the contributors section.
it can be accessed by anyone with the understanding that there is no
support for it.


David E. Jones sent the following on 6/27/2006 12:12 PM:

>
> As general feedback on this: it would also be nice to have a distinction
> in the document between committers and contributors, and to make it
> clear that you do not need commit privileges or special privileges in
> any system in order to contribute, and that if you want to become a
> committer then start by working on various contributions. This is
> something I've thought about writing a number of times given various
> random questions from people who want to contribute to the project and
> are therefore requesting commit privileges and what not.
>
> -David
>
>
> Si Chen wrote:
>> Ok, so as a follow up to the write up of guidelines for committers, I
>> thought we should have some guildelines for contributors as well to
>> help them work with the project.
>>
>> 1.  Send in a signed ICLA to Apache.
>>
>> 2.  Follow coding conventions.
>>
>> 3.  Install the OFBIZ Subversion client configuration file (where is
>> this?)
>>
>> 4.  Discuss your features with the community.  What are you trying to
>> implement, and how are you planning to do it?  This is especially
>> important if you are new to the project.
>>
>> 5.  Write clear, well-commented and understandable code.  Don't take
>> shortcuts, especially around variable names and error or warning
>> messages.  Use understandable data structures.  Remember, somebody
>> else will be working with your code down the road.
>>
>> 6.  Start out with small contributions which are easier to review.  In
>> the process, get familiar with the project's coding style and "thought
>> process."
>>
>> 7.  Put your contributions on JIRA instead of emailing it directly to
>> the committers, so everybody can review and comment on it.
>>
>> 8.  Get other members of the community to try your patch.  Write the
>> users list and tell them what you've done and ask them to try it out
>> and vote for it.  This would help the committers when they are
>> reviewing your patches.
>>
>>
>> Si
>>
>

[David E. Jones]

BJ Freeman wrote:
> I agree, with the Jira in place, that is the default commit for
> contributors.
> More what I was saying was there would be a place for the contributors
> code to be that could be accessed, but not thru the official code section.
> so the code in Specialized would be moved to the contributors section.
> it can be accessed by anyone with the understanding that there is no
> support for it.

Is there "support" for anything...? ;)

[BJ Freeman]

ROTFLOL
my dad use to say everybody is equal just some more than others.
same with support.
for what support there is, there is less for contributions.
LOL.


David E. Jones sent the following on 6/27/2006 12:51 PM:

>
>
> BJ Freeman wrote:
>> I agree, with the Jira in place, that is the default commit for
>> contributors.
>> More what I was saying was there would be a place for the contributors
>> code to be that could be accessed, but not thru the official code
>> section.
>> so the code in Specialized would be moved to the contributors section.
>> it can be accessed by anyone with the understanding that there is no
>> support for it.
>
> Is there "support" for anything...? ;)
>