RFC: making our mode of operation more explicit

20 views
Skip to first unread message

Kohsuke Kawaguchi

unread,
Sep 6, 2011, 5:29:14 PM9/6/11
to jenkin...@googlegroups.com

The AI I got in the last project meeting [1], of writing our implicit
mode of operations into something more explicit, is growing into the
following document:

https://wiki.jenkins-ci.org/display/JENKINS/Governance+Document

I'd like to get this officially blessed in the future project meeting
--- I think it'd be a great accomplishment for Jenkins User Conference.

I'd appreciate any feedbacks and things that it needs to cover.


[1]
http://meetings.jenkins-ci.org/jenkins/2011/jenkins.2011-08-31-18.00.html
--
Kohsuke Kawaguchi http://kohsuke.org/

nicolas de loof

unread,
Sep 7, 2011, 3:28:14 AM9/7/11
to jenkin...@googlegroups.com
Looks good to me,
I've just added a link to bi-weekly meeting minutes archives

2011/9/6 Kohsuke Kawaguchi <k...@kohsuke.org>

Christoph Kutzinski

unread,
Sep 7, 2011, 10:57:27 AM9/7/11
to jenkin...@googlegroups.com
Very nice write-up indeed.

There's only one point where I have a slightly different opinion:

https://wiki.jenkins-ci.org/display/JENKINS/Governance+Document#GovernanceDocument-Plugins

"Since much of such local culture is implicit, new contributor shouldn’t worry too much about offending the culture by committing code. You can either try to contact existing developers upfront, or make a commit and accept the chance that they might revert that."


I think that the modus operandi should always be to ask the existing developers upfront before doing any commit. If there's no timely response (1 week or so), feel free to commit.

Another more open and still acceptable (to me) option would be to commit away, but at least inform the committers about it.


cheers
Kutzi


-------- Original-Nachricht --------
> Datum: Wed, 7 Sep 2011 09:28:14 +0200
> Von: nicolas de loof <nicolas...@gmail.com>
> An: jenkin...@googlegroups.com
> Betreff: Re: RFC: making our mode of operation more explicit

> Looks good to me,
> I've just added a link to bi-weekly meeting minutes archives
>
> 2011/9/6 Kohsuke Kawaguchi <k...@kohsuke.org>
>
> >
> > The AI I got in the last project meeting [1], of writing our implicit
> mode
> > of operations into something more explicit, is growing into the
> following
> > document:
> >
> >

> https://wiki.jenkins-ci.org/**display/JENKINS/Governance+**Document<https://wiki.jenkins-ci.org/display/JENKINS/Governance+Document>


> >
> > I'd like to get this officially blessed in the future project meeting
> --- I
> > think it'd be a great accomplishment for Jenkins User Conference.
> >
> > I'd appreciate any feedbacks and things that it needs to cover.
> >
> >

> > [1] http://meetings.jenkins-ci.**org/jenkins/2011/jenkins.2011-**
> >
> 08-31-18.00.html<http://meetings.jenkins-ci.org/jenkins/2011/jenkins.2011-08-31-18.00.html>

domi

unread,
Sep 7, 2011, 12:16:22 PM9/7/11
to jenkin...@googlegroups.com
Really nice writing - increasing my motivation even more!!!!!!
/Domi

Jerome Lacoste

unread,
Sep 10, 2011, 5:57:23 AM9/10/11
to jenkin...@googlegroups.com

Some comments:

==== Document structure:

The "Project structure" section lists mostly roles and also references things defined later (in "how we develop code"), e.g. core, plugins.
Because of the that maybe we should move the Code structure up. Also this section could be renamed as "Project roles" or "Project stakeholders".

In the document, we may also want to add some info about
* third party libraries (used in core or outside, e.g. in backend)
* patching third party libraries?
* infrastructure: plugin update center, git[hub], wiki, jenkins on jenkins, backend, etc
* maybe something about how jenkins itself is reused (for automation). I think "eating your own dog food" is not necessarily a goal but when it fits the pragmatic aspects, it's generally favored.


The overall toc would look like:

> who we are
> Philosophy
> License
> Code Structure (MOVED UP) (core, plugins, third party)
> Project Infrastructure (NEW)
> Project roles / Actors / Stakeholders
> Communication
> How we develop code (same as before but for core/plugins moved up)
> How to join the project


If you think this is meaningfull, I can change the document.








==== Nitpicks

== License

"The core is entirely in the MIT license, so are the most infrastructure code (that runs the project itself), and many plugins. We encourage hosted plugins to use the same MIT license, to simplify the story for users, but plugins are free to choose their own licenses, so long as it’s OSI-approved open-source license."

shouldn't there be something like "... and compatible with the core, i.e. don't prevent things allowed by the core license".

IANAL.

== lower barrier of entry

" is partly achieved by structuring the project to core, plugins, modules, and other independent pieces,"

* add links to the subsections defining those things, or maybe add a single link to the "Code structure" section (proposed earlier)

== "To become a core committer, one needs to sign CLA."

* the above sentence makes one think the CLA is ready, the page makes one think it isn't yet "This CLA will be based on Apache's". Clarify ?

== "Core committers are expected to be attentive to pending pull requests, and try to act on them quickly."

this is also valid for plugin writers, isn't it ?

== Core coding conventions

"We roughly follow Sun coding convention in the source code, and we use 4 space indentation and don’t use tabs. However, we do not believe in rigorously enforcing coding convention, and we don’t want to turn down contributions because their code format doesn’t match what we use. So consider this informational."

Maybe add something alon "It's generally more practical and appreciated if you submit changes that don't change the code format too much as it eases the coding review job. Try submitting formatting changes and functional changes in separate commits."

Vojtech Juranek

unread,
Sep 13, 2011, 3:46:55 AM9/13/11
to jenkin...@googlegroups.com
> I'd appreciate any feedbacks and things that it needs to cover.

Nice doc and IMHO very usefull for newcomers.
Currently I have no idea how to improve it (what else shoudl be covered), i.e.
I like it as it is

Kohsuke Kawaguchi

unread,
Sep 14, 2011, 1:59:44 PM9/14/11
to jenkin...@googlegroups.com, Christoph Kutzinski

Thanks. I've updated the text to say the following:
--------------
Since much of such local culture is implicit, it's often difficult to
tell from outside the operating culture of a given plugin. The safe rule
of thumb is to contact existing developers upfront before doing any
commit (but if there's no timely response in a week so, you should feel
free to commit.) Less actively maintained plugin tend not to have such
local culture, so in those cases, if you feel lucky you can commit
changes ahead and send a heads-up simultaneously, (and accept the
possibility that the changes get reverted.)

If you have trouble figuring out who to contact, the good fallback
option is the dev list.
--------------


--
Kohsuke Kawaguchi | CloudBees, Inc. | http://cloudbees.com/
Try Nectar, our professional version of Jenkins

Kohsuke Kawaguchi

unread,
Sep 14, 2011, 5:13:07 PM9/14/11
to jenkin...@googlegroups.com, Jerome Lacoste

Thanks for very detailed comments.

On 09/10/2011 02:57 AM, Jerome Lacoste wrote:
> I've made a few small changes
> (https://wiki.jenkins-ci.org/pages/diffpages.action?pageId=58001392&originalId=58001788

> <https://wiki.jenkins-ci.org/pages/diffpages.action?pageId=58001392&originalId=58001788>)


>
> Some comments:
>
> ==== Document structure:
>
> The "Project structure" section lists mostly roles and also references
> things defined later (in "how we develop code"), e.g. core, plugins.
> Because of the that maybe we should move the Code structure up. Also
> this section could be renamed as "Project roles" or "Project stakeholders".

Done. I believe I copied the section title from Apache document.


> In the document, we may also want to add some info about
> * third party libraries (used in core or outside, e.g. in backend)
> * patching third party libraries?

Added sections under the license.

> * infrastructure: plugin update center, git[hub], wiki, jenkins on
> jenkins, backend, etc

I've added those as well in the infra section. But now that I added it,
it might be better split off and maintained by the infra folks.


> * maybe something about how jenkins itself is reused (for automation). I
> think "eating your own dog food" is not necessarily a goal but when it
> fits the pragmatic aspects, it's generally favored.

Added "automation" under philosophy

> The overall toc would look like:
>
>> who we are
>> Philosophy
>> License
>> Code Structure (MOVED UP) (core, plugins, third party)
>> Project Infrastructure (NEW)
>> Project roles / Actors / Stakeholders
>> Communication
>> How we develop code (same as before but for core/plugins moved up)
>> How to join the project
>
> If you think this is meaningfull, I can change the document.

I'm not sure if I understand the "code structure" part and "how we
develop code" part. I believe you are suggesting we move some h3
subsections from "how we develop code" into new h2 section "code
structure", but not sure which subsections you intended to move.


> ==== Nitpicks
>
> == License
>
> "The core is entirely in the MIT license, so are the most infrastructure
> code (that runs the project itself), and many plugins. We encourage
> hosted plugins to use the same MIT license, to simplify the story for
> users, but plugins are free to choose their own licenses, so long as
> it’s OSI-approved open-source license."
>
> shouldn't there be something like "... and compatible with the core,
> i.e. don't prevent things allowed by the core license".
>
> IANAL.

I think plugins are allowed to restrict certain rights on themselves
that core would allow to core. For example, when you develop an ASL
licensed plugin, you are making users agree that any patch submitted
would be also under ASL unless explicitly said otherwise. Core being MIT
doesn't say that.

MIT being more liberal, if we require that plugins grant all the rights
that core grant for itself, then we'd be effectively forcing all to be MIT.

Perhaps you mean "plugins shouldn't impose any additional restrictions
on the core", but that is actually one of the freedom allowed by MIT (to
combine it with some non-free code), so I don't think we want to say
that either.

> == lower barrier of entry
>
> " is partly achieved by structuring the project to core, plugins,
> modules, and other independent pieces,"
>
> * add links to the subsections defining those things, or maybe add a
> single link to the "Code structure" section (proposed earlier)

Done. Added hyperlinks.


> == "To become a core committer, one needs to sign CLA."
>
> * the above sentence makes one think the CLA is ready, the page makes
> one think it isn't yet "This CLA will be based on Apache's". Clarify ?

I was shooting for ratifying both this and CLA at the same time. More
about this in a separate e-mail.

> == "Core committers are expected to be attentive to pending pull
> requests, and try to act on them quickly."
>
> this is also valid for plugin writers, isn't it ?

I think this is covered more extensively in the "Using pull requests"
section in the end, so I think it's OK.


> == Core coding conventions
>
> "We roughly followSun coding convention

> <http://www.oracle.com/technetwork/java/codeconv-138413.html>in the


> source code, and we use 4 space indentation and don’t use tabs. However,
> we do not believe in rigorously enforcing coding convention, and we
> don’t want to turn down contributions because their code format doesn’t
> match what we use. So consider this informational."
>
> Maybe add something alon "It's generally more practical and appreciated
> if you submit changes that don't change the code format too much as it
> eases the coding review job. Try submitting formatting changes and
> functional changes in separate commits."

Added. This is also discussed in the "Using pull requests" section.

Reply all
Reply to author
Forward
0 new messages