Contributor and commiter guidelines (was Re: Committer guidelines)

[Antonio <an...@vieiro.net>]

Hi again,

I recall reading Jesse's excellent pieces of advice a while back in the 
mailing list, about branching, forking and proper git use.

First things first, I'll try to recover those end ensure they are 
included in the guidelines for contributors and committers.

Cheers,
Antonio

On 17/11/17 09:01, Antonio wrote:
> Thanks, Wade, for the pointers.
> 
> I didn't know about this effort. Of course I'll try it out and count me 
> as a contributor. I'll read your previous emails and see what's required.
> 
> Kind regards,
> Antonio
> 
> On 17/11/17 06:21, Wade Chandler wrote:
>>> On Nov 16, 2017, at 16:42, Antonio <an...@vieiro.net> wrote:
>>>
>>> Hi,
>>>
>>> I was wondering if there're any guidelines for new committers. I 
>>> assume that the ones at https://netbeans.org/community/guidelines/ 
>>> still apply after the Apache donation. We could update that and add 
>>> this to our web, right?
>>
>> That file is in the web site that I’m aggregating. I have sent emails 
>> to this list about how to contribute in the past, so I assume you can 
>> find those. At the moment I’m working here 
>> https://github.com/wadechandler/netbeans-static-site 
>> <https://github.com/wadechandler/netbeans-static-site> to get things 
>> cleaned up, and then plan for that to overwrite the Apache NetBeans 
>> repository once cleaned up “to a point” to keep the repo from bloating 
>> due to zips etc in the site sources, and to have a clean history. The 
>> two sites are being blended. There is a component called “website” in 
>> Apache NetBeans Jira, and you can see the stories here if you have any 
>> to add/etc 
>> https://issues.apache.org/jira/browse/NETBEANS-124?jql=project%20%3D%20NETBEANS%20AND%20component%20%3D%20website 
>> <https://issues.apache.org/jira/browse/NETBEANS-124?jql=project%20=%20NETBEANS%20AND%20component%20=%20website> 
>>
>>
>> There is a good bit to do there, and like I said before when I emailed 
>> this list, if anyone would like to contribute, you can either send PRs 
>> or I can make people contributors on github if they get me their GH 
>> user ID. Gj is one.
>>
>> As far as the guidelines go, and as far as I understand, yes, a good 
>> bit of that is still applicable from the discussions on the list, but 
>> of course we are now using RTC for things other than small ones (even 
>> for committers) or at least we have discussed it. If we are not in 
>> agreement on that, then we should start a new thread and hash that out 
>> of course.
>>
>> The rest, if anyone objects perhaps we need a new thread for each 
>> piece or at least a small enough chunk of relative areas to discuss.
>>
>>>
>>> Also, would any committer please export & share the code formatting 
>>> options for NetBeans?
>>>
>>
>> My understanding and as it has worked out throughout my contributions 
>> is that the NB sources use NBs default formatting. But if wrong, 
>> someone please correct me.
>>
>> Thanks,
>>
>> Wade
>>
>>

Re: Contributor and commiter guidelines (was Re: Committer guidelines)

[Antonio <an...@vieiro.net>]

I don't know, my memory is not that good anymore. That's why I prefer 
having things written somewhere. Anyway I think it's a good idea to 
include some github best practices for both contributors and committers.

Regarding resistence to it, I just don't remember: I'll find out.

Cheers,
Antonio

El 17/11/17 a las 13:22, Neil C Smith escribió:
> On Fri, Nov 17, 2017 at 12:56 PM Antonio <an...@vieiro.net> wrote:
> 
>> I recall reading Jesse's excellent pieces of advice a while back in the
>> mailing list, about branching, forking and proper git use.
>>
>> First things first, I'll try to recover those end ensure they are
>> included in the guidelines for contributors and committers.
>>
> 
> To be pedantic, if it's the email I'm thinking of, it's about GitHub
> workflow not git workflow, and it's in the pattern matching thread.  I had
> the feeling only he and I had advocated for that way of working though and
> there was some resistance to it?
> 
> Best wishes,
> 
> Neil
> 

Re: Contributor and commiter guidelines (was Re: Committer guidelines)

[Lars Bruun-Hansen <lb...@gmail.com>]

Slightly off topic because this is about contributors (not committers) to
Apache NetBeans:

There are some unfinished scribbles here:

https://cwiki.apache.org/confluence/pages/viewpage.action?pageId=74681408

Note comments from Jesse in the right hand margin. (scroll down)

Feel free to amend, move or whatever, but I guess it is best to keep
guidelines for committers and contributors apart.

And yet another topic:  Commit messages !
Yes, it is almost a topic of its own. Linus T has some very specific
viewpoints on it (surprise!) which means that allegedly the Linux Kernel
project has excellent commit messages, and PRs are supposedly refused if
the commit message doesn't live up to this standard. I don't think Apache
NetBeans should be as dogmatic but looking back at Hg it seems there's been
no "best practice" at all in the past. A few lines of what a good message
looks like would be enough, I think.  Writing good commit messages applies
to both committers and contributors. (btw: I learned my lesson from
Matthias :-))




On Sat, Nov 18, 2017 at 1:53 PM, Neil C Smith <ne...@apache.org> wrote:

> Hi Jan,
>
> On Sat, 18 Nov 2017, 13:28 Jan Lahoda, <la...@gmail.com> wrote:
>
> > 2. work on a branch in the main repo (or a "prototypes" repository), but
> > only push using pull requests to it (which is what I understand is Neil
> > proposing)
> > 3. work on a branch in one's GitHub repo, but have a perpetual pull
> request
> > open against the main repo covering the work (which is what was my
> original
> > understanding of what Jesse was proposing)
> > 4. work on a branch in one's GitHub repo, send pull request when ready
> >
>
> If you read back through what Jesse and I have said, in particular his last
> email in that thread, I find it really difficult to find any fundamental
> difference between these 3 options.
>
> One way of looking at it might be that you do your work on your fork repo
> (you being anyone!), we all collaborate through the ASF repo. A PR is a
> discrete piece of work that makes sense to merge - some perhaps to master
> for release, some to a development branch if it's a big feature that
> requires collaboration.
>
> btw - I wasn't suggesting a PR per push, but for each discrete thing that
> was ready to share.
>
> Best wishes,
>
> Neil
>
> > --
> Neil C Smith
> Artist & Technologist
> www.neilcsmith.net
>
> Praxis LIVE - hybrid visual IDE for creative coding - www.praxislive.org
>

Re: Contributor and commiter guidelines (was Re: Committer guidelines)

[Jan Lahoda <la...@gmail.com>]

On Sat, Nov 18, 2017 at 1:53 PM, Neil C Smith <ne...@apache.org> wrote:

> Hi Jan,
>
> On Sat, 18 Nov 2017, 13:28 Jan Lahoda, <la...@gmail.com> wrote:
>
> > 2. work on a branch in the main repo (or a "prototypes" repository), but
> > only push using pull requests to it (which is what I understand is Neil
> > proposing)
> > 3. work on a branch in one's GitHub repo, but have a perpetual pull
> request
> > open against the main repo covering the work (which is what was my
> original
> > understanding of what Jesse was proposing)
> > 4. work on a branch in one's GitHub repo, send pull request when ready
> >
>
> If you read back through what Jesse and I have said, in particular his last
> email in that thread, I find it really difficult to find any fundamental
> difference between these 3 options.
>

The option "4" above was meant "work in GitHub until ready for master"
(which was also proposed in the patterns thread). The obvious disadvantage
being that we (AFAIK) can't use that code until it is contributed to the
ASF.


>
> One way of looking at it might be that you do your work on your fork repo
> (you being anyone!), we all collaborate through the ASF repo. A PR is a
> discrete piece of work that makes sense to merge - some perhaps to master
> for release, some to a development branch if it's a big feature that
> requires collaboration.
>
> btw - I wasn't suggesting a PR per push, but for each discrete thing that
> was ready to share.
>

I guess I wonder what is a "discrete thing that is ready to share". Some
examples:
https://github.com/jlahoda/incubator-netbeans/tree/jdk/amber/datum
https://github.com/apache/incubator-netbeans/tree/jdk/amber/patterns
https://github.com/apache/incubator-netbeans/tree/jdk-javac
https://github.com/apache/incubator-netbeans/commit/44f8c1dfc24a980fec4642a992c380e3d1f27ab6
https://github.com/apache/incubator-netbeans/commit/6c5403a23dad6319719da7c0803387d8721e4476

 In all these cases, I find it easy to argue both ways (it is particularly
easy to argue that datum is unfinished and not ready, as it does not
support e.g. code completion).

Jan


> Best wishes,
>
> Neil
>
> > --
> Neil C Smith
> Artist & Technologist
> www.neilcsmith.net
>
> Praxis LIVE - hybrid visual IDE for creative coding - www.praxislive.org
>

Re: Contributor and commiter guidelines (was Re: Committer guidelines)

[Neil C Smith <ne...@apache.org>]

Hi Jan,

On Sat, 18 Nov 2017, 13:28 Jan Lahoda, <la...@gmail.com> wrote:

> 2. work on a branch in the main repo (or a "prototypes" repository), but
> only push using pull requests to it (which is what I understand is Neil
> proposing)
> 3. work on a branch in one's GitHub repo, but have a perpetual pull request
> open against the main repo covering the work (which is what was my original
> understanding of what Jesse was proposing)
> 4. work on a branch in one's GitHub repo, send pull request when ready
>

If you read back through what Jesse and I have said, in particular his last
email in that thread, I find it really difficult to find any fundamental
difference between these 3 options.

One way of looking at it might be that you do your work on your fork repo
(you being anyone!), we all collaborate through the ASF repo. A PR is a
discrete piece of work that makes sense to merge - some perhaps to master
for release, some to a development branch if it's a big feature that
requires collaboration.

btw - I wasn't suggesting a PR per push, but for each discrete thing that
was ready to share.

Best wishes,

Neil

> --
Neil C Smith
Artist & Technologist
www.neilcsmith.net

Praxis LIVE - hybrid visual IDE for creative coding - www.praxislive.org

Re: Contributor and commiter guidelines (was Re: Committer guidelines)

[Jan Lahoda <la...@gmail.com>]

On Fri, Nov 17, 2017 at 1:22 PM, Neil C Smith <ne...@apache.org> wrote:

> On Fri, Nov 17, 2017 at 12:56 PM Antonio <an...@vieiro.net> wrote:
>
> > I recall reading Jesse's excellent pieces of advice a while back in the
> > mailing list, about branching, forking and proper git use.
> >
> > First things first, I'll try to recover those end ensure they are
> > included in the guidelines for contributors and committers.
> >
>
> To be pedantic, if it's the email I'm thinking of, it's about GitHub
> workflow not git workflow, and it's in the pattern matching thread.  I had
> the feeling only he and I had advocated for that way of working though and
> there was some resistance to it?
>

I guess there are several different scenarios. To get things to master, we
currently use pull requests, and I don't think anyone is objecting to that.
The discussion in the patterns thread was mostly about long(er)-term
development on a branch (which may or may not end up in the master, but is
unlikely to end up there soon). IIRC the following approaches have been
mentioned:
1. work on a branch in the main repo, commit directly to it
1a. a sub-variant: use a special "prototypes" repository under ASF for
these development branches
2. work on a branch in the main repo (or a "prototypes" repository), but
only push using pull requests to it (which is what I understand is Neil
proposing)
3. work on a branch in one's GitHub repo, but have a perpetual pull request
open against the main repo covering the work (which is what was my original
understanding of what Jesse was proposing)
4. work on a branch in one's GitHub repo, send pull request when ready

One thing to note is that if we pick variant "N" from these as the correct
one, a developer in a particular situation can choose to use some variant
below N.

I think it is desirable to encourage work under an ASF repo if possible (to
keep code provenance clear). My personal preference would be 1 or 1a (which
for the person doing the development are mostly equivalent), but can live
with the other options as well. Just seems unnecessary to do pull requests
for a development branch which is typically OK to be broken, and used only
by a handful of developers.

Jan


> Best wishes,
>
> Neil
> --
> Neil C Smith
> Artist & Technologist
> www.neilcsmith.net
>
> Praxis LIVE - hybrid visual IDE for creative coding - www.praxislive.org
>

Re: Contributor and commiter guidelines (was Re: Committer guidelines)

[Neil C Smith <ne...@apache.org>]

On Fri, Nov 17, 2017 at 12:56 PM Antonio <an...@vieiro.net> wrote:

> I recall reading Jesse's excellent pieces of advice a while back in the
> mailing list, about branching, forking and proper git use.
>
> First things first, I'll try to recover those end ensure they are
> included in the guidelines for contributors and committers.
>

To be pedantic, if it's the email I'm thinking of, it's about GitHub
workflow not git workflow, and it's in the pattern matching thread.  I had
the feeling only he and I had advocated for that way of working though and
there was some resistance to it?

Best wishes,

Neil
-- 
Neil C Smith
Artist & Technologist
www.neilcsmith.net

Praxis LIVE - hybrid visual IDE for creative coding - www.praxislive.org