Request for feedback: Jenkins Enhancement Proposal (JEP)

[R. Tyler Croy]

At the Jenkins World Contributor Summit a couple weeks ago, I shared some
thoughts I have been having on how we can continue to grow and improve Jenkins.
One of those thoughts centers around the fundamental challenge: how do we, as a
group, make large transformational changes to Jenkins (and still get along and
like each other during the process).

Python users may recognize this structure, which is how the Python community
has organized their work. PEP in the Python community has allowed Python to
make *massive* changes over the past 15 years to what Python is, without
killing each other (very important).


I would like to propose the following process of a "Jenkins Enhancement
Proposal":

https://github.com/jenkinsci/jep/tree/jep-1/jep/1


The overarching rationale for this proposal can be found in the rationale
section: https://github.com/jenkinsci/jep/tree/jep-1/jep/1#rationale

I also created an example of an Informational JEP here:
https://github.com/jenkinsci/jep/pull/2


For discussion on this foundational JEP, I suggest using this mailing list
thread. To propose changes, or fix some verbiage, feel free to open a pull
request targeting that `jep-1` branch.


To agree to this change in process, I don't think a "BDFL" or "BDFL-Delegate"
approval itself (read the doc) is sufficient. I think we should try to reach
consensus on this thread, and assuming there's consensus, approve the proposal
during the next Governance Meeting (Sept 27th).


Feel free to ping me via email or IRC if you have questions which you do not
feel belong in the mailing list discussion.


Thank you in advance for spending the time to read JEP-1 :)


Cheers
- R. Tyler Croy

------------------------------------------------------
Code: <https://github.com/rtyler>
Chatter: <https://twitter.com/agentdero>
xmpp: rty...@jabber.org

% gpg --keyserver keys.gnupg.net --recv-key 1426C7DC3F51E16F
------------------------------------------------------

[Oliver Gondža]

I suspect this question might have been asked in the room but are we ok
with the name collisions with Java Enhancement Proposals? Which one we
are referring to should be straightforward from the context but when
this becomes more widespread and changes will be refereed to by their
IDs, google searches will be quite confusing especially given the fact
the areas are somewhat related. How about JIP? or JEEP :P

--
oliver

[Jesse Glick]

On Wed, Sep 13, 2017 at 3:55 PM, Oliver Gondža <ogo...@gmail.com> wrote:
> I suspect this question might have been asked in the room but are we ok with
> the name collisions with Java Enhancement Proposals?

I had the same thought. JKEP-nnn?

[R. Tyler Croy]

(replies inline)

If I recall correctly, Jesse did mention the Java Enhancement Proposals acronym
collision at the Contributor Summit.

Personally, I'm not bothered at all by it at since jenkins.io and
openjdk.java.net are pretty distinguishable. If the acronym is of extremely high
importance to somebody, I don't mind changing to something similarly short and
understandable. No yak-shaving on acronyms allowed though :P

[Jesse Glick]

On Wed, Sep 13, 2017 at 3:32 PM, R. Tyler Croy <ty...@monkeypox.org> wrote:
> I think we should try to reach
> consensus on this thread

Sounds like a good idea to me! Structure seems pretty clear.

[Keith Zantow]

... random suggestion: "JPI" Jenkins Proposal Initiative/Initiation.

--
You received this message because you are subscribed to the Google Groups "Jenkins Developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email to jenkinsci-dev+unsubscribe@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/jenkinsci-dev/CANfRfr32TJTKwgWmM5oegVZDGCOHnxV-9EoDaO%2B71jBh6zR5-g%40mail.gmail.com.

For more options, visit https://groups.google.com/d/optout.

[Owen Mehegan]

Having read and edited JEP-1, I am in favor of this idea as presented :)

To view this discussion on the web visit https://groups.google.com/d/msgid/jenkinsci-dev/CAJTHQaGTECfjPPq_kDt81YEUuWubTmyAqq7b1X%2B4YoGtMrGJDw%40mail.gmail.com.

[Liam Newman]

I think this is great idea. I agree with the proposed process.

 

I think the proposal document itself could use some tweaks, which I've suggested in PR (oops oh well). 

[R. Tyler Croy]

(replies inline)

On Wed, 13 Sep 2017, Liam Newman wrote:

> I think this is great idea. I agree with the proposed process.
>
> I think the proposal document itself could use some tweaks, which I've
> suggested in PR (oops oh well).

No worries whatsoever! This is still fresh from the oven, so it's no problem
whatsoever to "cross the streams" which we get comfortable with a workflow
here.

I have addressed many of your comments in a pull request to the `jep-1` branch
here: https://github.com/jenkinsci/jep/pull/3


Of particular note for this group are some additions which I think Liam's 100%
in requesting, namely:

* Consistently using Must/Should/May (https://github.com/jenkinsci/jep/pull/3/files#diff-43894e615b82e2536b1341c33ff49afeR116)
* Structuring JEP-1 more closely with the sections JEP-1 outlines as important (https://github.com/jenkinsci/jep/pull/3/files#diff-43894e615b82e2536b1341c33ff49afeR565)



Thanks for helping!

[R. Tyler Croy]

(replies inline)

On Wed, 13 Sep 2017, R. Tyler Croy wrote:

> https://github.com/jenkinsci/jep/tree/jep-1/jep/1


Since I'm sure not everybody has been following along with some of the pull
requests and changes while we've been hammering out JEP-1, I would like to
provide a little bit of an update and solicit some help. This topic is very
important, so please read this email!

First, thanks to reviews from a number of folks including Oleg, Owen, Daniel,
and others, we have been able to tighten the proposal up quite a bit. Mostly
thanks to Liam's diligent slicing and dicing of text :)

While I had hoped we might be able to get some consensus in time for tomorrow's
project meeting, I don't think we are quite there yet. There has been lots of
helpful feedback on the review and decision-making process (BDFL/BDFL-delegate):
https://github.com/jenkinsci/jep/tree/jep-1/jep/1#review


To summarize the primary, and valid, criticisms if I may:

1. Kohsuke as the BDFL introduces a problematic bottleneck to the process
(there are way more of us, than there are of him).

2. JEP-1 introduces a different way of decision making than has been
traditionally followed with the Governance Meeting
(https://jenkins.io/project/governance/#meeting)


I would like to guide the discussion towards addressing these. I also want to
ensure our process is sensitive to contributors around the world, especially
those in Australia and Asia who are typically asleep during the scheduled
project meetings and rely on asynchronous mediums like email.

If you have an example structure for technical decision-making from another
project, which you think is applicable, please chime in!


Personally, what I'm thinking right now is to flip the Python model upside
down: when the JEP Author creates a draft they (or a JEP Editor) list a
"Delegate" who would be somebody with good standing as the maintainer of that
subject area, other than themselves.

For example, if I were proposing a design on Remoting, Oleg would be the
obvious Delegate. If Andrew were proposing some design around Pipeline, Jesse
would be a reasonable Delegate. Rather than expecting a BDFL to be "plugged
into" each JEP, we self-select more (which I think we're all capable of doing).
For the times when we might have conflcit, then we can use the Governance
Meeting process to resolve who the appropriate Delegate for a proposal may be.
To help new comers, including a list of "Suggested Delegates" in the JEP repo
could also be helpful.

I think that could avoid the problems with the current BDFL proposal, while
reducing the need to run every JEP through the Governance Meeting process,
where not all the stakeholders will necessarily be present.



Of course, I'm open to more suggestions and discussion. Like I said at the
beginning of the email, I think getting this right is important.

[Robert Sandell]

I didn't get the sense that the BDFL would be a bottle neck when you explained it to us at the contributor summit.

To me it seemed like the BDFL would only have to get involved if consensus between the author, editors and other reviewers can't be reached, or if he needs to put in a veto to stop something (in his mind) crazy from happening.

That said having Subject Matter Experts on hand to either serve as a "Deputy BDFL" for a specific area, or just someone that gets an explicit ping when a JEP affecting "their" area comes in might be good to have.

/B

--
You received this message because you are subscribed to the Google Groups "Jenkins Developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email to jenkinsci-dev+unsubscribe@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/jenkinsci-dev/20170919171212.j3sjo4fawhisfieb%40blackberry.coupleofllamas.com.

For more options, visit https://groups.google.com/d/optout.

--

Robert Sandell

Software Engineer

CloudBees Inc.

[Daniel Beck]

> On 19. Sep 2017, at 19:12, R. Tyler Croy <ty...@monkeypox.org> wrote:
>
> While I had hoped we might be able to get some consensus in time for tomorrow's
> project meeting

There was none, it is (and always has been) scheduled for next week, September 27.

Just general FYI to prevent confusion.

> Personally, what I'm thinking right now is to flip the Python model upside
> down: when the JEP Author creates a draft they (or a JEP Editor) list a
> "Delegate" who would be somebody with good standing as the maintainer of that
> subject area, other than themselves.
>
> For example, if I were proposing a design on Remoting, Oleg would be the
> obvious Delegate. If Andrew were proposing some design around Pipeline, Jesse
> would be a reasonable Delegate. Rather than expecting a BDFL to be "plugged
> into" each JEP, we self-select more (which I think we're all capable of doing).
> For the times when we might have conflcit, then we can use the Governance
> Meeting process to resolve who the appropriate Delegate for a proposal may be.
> To help new comers, including a list of "Suggested Delegates" in the JEP repo
> could also be helpful.

This seems reasonable.

I don't remember where I saw this, but a large (web browser perhaps?) project had their entire source code organized in nested directories that each optionally specify a (list of) 'component owners', and the rule that changed have to be signed off by the appropriate owners, preferring the more specific (towards deeply nested) owners over the less specific (towards root directory). I thought this was a neat idea back then, and see some similarities to this proposal.

But AFAIUI, there's no strict requirement to make a specific contributor the delegate though, even if considered the maintainer, right? Can Oleg self-assign any remoting JEP, or would editors be expected to redirect mismatched requested delegates? Or how would that be handled? Also, how would Oleg propose large-scale remoting changes (it needs to be "other than themselves")? I expect the lack of widespread expertise here might be a major impediment in some subject areas.

My apologies to Oleg for keeping bringing him/remoting up as example, but AFAICT remoting is one of few examples of a 'core' component with a single maintainer and no obvious alternative maintainer.

The above questions notwithstanding, I think this approach is something we can get started with, and maybe adjust after a year or so if it doesn't work out for any reason. I don't expect it won't, but who knows. I like how in some areas we're not defining the details overly restrictively when we need to see how things work out.

[Oleg Nenashev]

Hi all,

Sorry for being silent. I have blocked the original PR due to the BDFL concern, so I wanted to let others to provide feedback.

The flip-down model works for me. It is pretty similar to what I proposed here ("Governance meeting mode"), so definitely +1. It prevents the potential bottleneck and keeps JEP compliant with the current Governance Meeting - driven process. From what I see, it allows excluding the "BDFL" entity from the document for now. Generally I am in favor of introducing the BDFL role, but I would do it in a separate JEP.

Regarding the process, some minor comments...

• I would expect Delegates to be discussed in the mailing list before the JEP submission, so it just needs approval at the governance meeting. I hope it also resolves the timezone difference concern, because anybody will be able to cast their votes in the mailing list in advance.
• Having multiple delegates would be useful in the case of shared areas like Jenkins Core. In order to JEP to be accepted, all delegates should either vote "yes" or abstain. If a delegate gets assigned, it seems reasonable to grant a veto right (or not?).

BR, Oleg

суббота, 23 сентября 2017 г., 15:30:39 UTC+3 пользователь Daniel Beck написал:

[Daniel Beck]

> On 27. Sep 2017, at 11:36, Oleg Nenashev <o.v.ne...@gmail.com> wrote:
>
> Regarding the process, some minor comments...
> • I would expect Delegates to be discussed in the mailing list before the JEP submission, so it just needs approval at the governance meeting.

TBH the group of potential delegates is fairly small. I expect we'll be able to self-select as appropriate, so I don't see the point in planning for the worst imaginable outcome. It'll just make for an unwieldy, bloated process. The best way to ensure that nothing ever gets done is to require project meeting involvement. On top of that, it excludes contributors from several continents. (And if people from those continents can 'vote from the mailing list', as you mention, why even tie it to the meeting?)

[Oleg Nenashev]

If there is a consensus in the mailing list, no strict need to involve the governance meeting from the technical PoV. The only purpose of the governance meeting here is to...

• Act as a arbiter when there is no agreement in the mailing list
  
• To legitimate the decisions, so that the proposal (accept JEP for review, assign delegates) becomes an official decision by the Jenkins project. It may prevent conflicts in the following cases:
• JEP gets rejected, the submitter blames delegates due to a conflict of interest
  
• JEP gets accepted, somebody chimes later and grumbles that people ignored his feedback and didn't select him as one of the delegates

So my point about the Governance Meeting is rather a protective one, it protects both community and delegates. In some cases it will be "process just for the process" for sure. Currently the Governance Meeting is IMHO the only legitimate institution in Jenkins (no "technical steering committee", board election fun), so that's why I propose to route the approval through the governance meeting.

BR, Oleg

--
You received this message because you are subscribed to a topic in the Google Groups "Jenkins Developers" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/jenkinsci-dev/spDAr8EJm3c/unsubscribe.
To unsubscribe from this group and all its topics, send an email to jenkinsci-dev+unsubscribe@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/jenkinsci-dev/EB23042E-B108-462F-991C-845BF568A3E9%40beckweb.net.

[Daniel Beck]

> On 27. Sep 2017, at 12:06, Oleg Nenashev <o.v.ne...@gmail.com> wrote:
>
> If there is a consensus in the mailing list, no strict need to involve the governance meeting from the technical PoV. The only purpose of the governance meeting here is to...
> • Act as a arbiter when there is no agreement in the mailing list

Right, but we can just start a vote on the mailing list, too. Especially if half the people (or at least half the continents) would need to do that anyway.

> • To legitimate the decisions, so that the proposal (accept JEP for review, assign delegates) becomes an official decision by the Jenkins project. It may prevent conflicts in the following cases:

> • JEP gets rejected, the submitter blames delegates due to a conflict of interest

Should have chosen a different delegate then (remember, author chooses -- but I expect e.g. not choosing you for remoting will raise lots of eyebrows and will make people look closely).

> • JEP gets accepted, somebody chimes later and grumbles that people ignored his feedback and didn't select him as one of the delegates

If it's feedback by a single individual and everyone else is fine, that's consensus building in action. Consensus doesn't mean decisions need to be unanimous.

(Which is why I'd prefer to have rules specifying the security officer can veto for security reasons, and infra team lead can veto for infra reasons, but I trust that those concerns would be addressed in the process we're designing right now -- and if not, we'll adapt the process as needed.)

If the delegate actually ignores concerns brought by a majority of reviewers, I'd reconsider the eligibility of the delegate for future JEPs.

> So my point about the Governance Meeting is rather a protective one, it protects both community and delegates. In some cases it will be "process just for the process" for sure. Currently the Governance Meeting is IMHO the only legitimate institution in Jenkins (no "technical steering committee", board election fun), so that's why I propose to route the approval through the governance meeting.

If we're agreeing that this involvement of the project meeting would be a rare occurrence handling exceptional cases (if it's going to be 10% of JEPs we're still terrible), sure. But it still seems similar to adding rules for what should happen when we just start insulting or doxing each other. As in: if this happens, we have larger problems.

[R. Tyler Croy]

There has been a tremendous amount of productive discussion, with a lot of
helpful editing work by Liam. I think the process is ready for an approval in a
Governance meeting, so I'm going to put the proposal on the agenda for the Oct
11th meeting.


Proposal:

https://github.com/jenkinsci/jep/tree/jep-1/jep/1


If you will be unable to join during the meeting, please respond to this thread
with your yay or nay.

[Daniel Beck]

> On 5. Oct 2017, at 18:01, R. Tyler Croy <ty...@monkeypox.org> wrote:
>
> There has been a tremendous amount of productive discussion, with a lot of
> helpful editing work by Liam. I think the process is ready for an approval in a
> Governance meeting, so I'm going to put the proposal on the agenda for the Oct
> 11th meeting.
>
>
> Proposal:
>
> https://github.com/jenkinsci/jep/tree/jep-1/jep/1
>
>
> If you will be unable to join during the meeting, please respond to this thread
> with your yay or nay.

Tyler requested this topic be postponed to next meeting, as he's unable to make it to today's meeting.

So we all have two more weeks now to think about this proposal and provide feedback ;-)

[Jesse Glick]

As an aside, it just occurred to me that JENKINS-41745 is something
that I would have done as a JEP had that existed at the time. Having
the templates and structure in place would have made it easier to
write up the proposal

https://gist.github.com/jglick/9721427da892a9b2f75dc5bc09f8e6b3

and of course would have provided a nicer permalink. :-)

[Daniel Beck]

Good point. That reminds me that I wrote up somewhat detailed proposals for changes to project infrastructure over the last year or so (first the introduction fine-grained Maven upload permissions, and later cutting the wiki dependency out of plugin distributions).

While those were nonpublic since they discuss (at the time) easily exploitable properties of the infra and how that would be fixed, being able to have that in a standard format, and publish it afterwards as documentation, would have been useful. (And I expect I'll need to make those into informational JEPs in the future…)

[Liam Newman]

In the latest change, I've proposed removing the BDFL role.

https://github.com/jenkinsci/jep/pull/18 to see the changes.

(Note: in a previous PR I replaced the BDFL-delegate role with a "Reviewer" role and had expanded the description of BDFL.)

I got it this far, but I'm out of bandwidth to make further changes this week.

Oleg had some valid questions, and said he'd try to submit a PR addressing them.

If anyone else wants to pick up a little of the load here, that'd be great - comments welcome, PRs preferred. 

Thanks,

Liam Newman

[Kohsuke Kawaguchi]

I admit I kept my eyes off this ball for a while. Naturally, I'm surprised at this change.

My understanding was that this change is being considered as a reaction to those two concerns:

> 1. Kohsuke as the BDFL introduces a problematic bottleneck to the process

>    (there are way more of us, than there are of him).

>

> 2. JEP-1 introduces a different way of decision making than has been

>    traditionally followed with the Governance Meeting

>    (https://jenkins.io/project/governance/#meeting)

I prefer the original "BDFL + Delegate" model. I'd like to explain the reasons, and why that model adequately address those concerns. This is going to be a long post.

First, the bottleneck point. As Bobby said in this thread and was discussed in the contributor summit, I understood my role in this process to be more like British Queen or Japanese Emperor, in the sense that I'm expected to designate Delegate in each area and let them lead those areas, as opposed to Supreme Court Justice who preside over individual cases. That is, the idea is to influence Delegates instead of influencing JEPs. In this manner, I don't think BDFL will be a bottleneck.

The obvious question then would be how I pick Delegate. I think most area has natural leads that owns the spaces. For example, Daniel leads security related things, Oleg leads remoting, Jesse leads Pipeline, and so on. Those people currently have implicit influences, and we know who they are. I intend to designate them as Delegate. I will discuss that designation beforehand to eliminate any chance of surprises.

This brings me to one of the reasons why I'm supporting JEP. Today, people who lead various efforts do so solely based on implicit influence. But this scheme doesn't work well as we scale up. I see the Delegate title as a way to make those implicit influences more explicit, so that people who are not spending as much time in the project or contributors from organizations can easily identify them as the primary go-to guy. Put differently, I want the Delegate title to help those people lead more effectively. The officer title worked very well with this regard. I think of Delegate as technical version of it. Obviously, we don't want Delegate to be dictators any more than you want BDFL to be actual dictator.And that spirit is captured in JEP. We expect Delegate to understand implicit influences of other people in neighboring areas and bring them in as appropriate.

One of the problems I have with the proposed self-nominated Reviewer scheme is that it does not help with this regard. There's no explicit title like "Delegate" to clarify the role of leads. Those leads still need to rely solely on implicit influences.

Back to how to pick Delegate. When we start a new effort, in the area where there's no existing effort, say Jenkins 2 or pluggable storage, I expect the initial JEP to capture goals and high level requirements of that effort. I will be the reviewer of that initial JEP, but as a part of that JEP I expect the Delegate to be determined for that space. Oftentimes the sponsor of that JEP should be the obvious choice as the Delegate as the leader of the effort. Other times we may need to have more discussions among the core developers to determine that person. Subsequent JEP in that space, to the extent it stays within the charter of the initial JEP, should be presided by that Delegate.

This brings me to another reason why I'm supporting JEP. Organized contributors (aka companies putting their people into the project, as opposed to individuals participating on their own initiatives) need this kind of marking the space in which they execute in. Before driving a non-trivial effort, there needs to be discussion and consensus that the project accepts the idea (e.g., "there should be Jenkins 2 whose goals are this and that".) Once that idea is agreed upon, we need to respect the authority of the group who's working on it. They can't work on anything non trivial if there's some sense that the work will be accepted in the end. And often, people who lead those efforts have limited visibility in the project. This came up multiple times in my conversation with potential corporate contributors outside CloudBees.

One of the problems I have with the removal of Delegate is that we lose the tool to help make this authority explicit. And likewise, we lose the continuity of Delegate. I hope we will have a lot of different Sponsors trying to drive changes in the same area, and we need Delegate ensures that there's some consistency and continuity, which requires a stable Delegate.

As for the second concern of the decision making structure outside the governance meeting, I think what I'm describing above is very much in line with how we have been operating on technical matters. We never really used the governance meeting as a venue for technical decision making, and that's the way I think it should be. It obviously provides a great place for synchronous communication to bring people to some consensus faster, like new LTS base version, but only a specific subset of people who work on Jenkins are there.

One of my goals in JEP is to clarify the path of technical decision making. The original proposal does this by symbolically rooting the chain of authority to BDFL (like how Queen and Emperor symbolically empowers the elected government.) The removal of BDFL + Delegate tries to root the chain of authority to "consensus of core contributors", but that fails to achieve this goal because "core contributors" is not a group with clear boundary, and we don't know how far "consensus" needs to be reached.

So there it is. I argue we should accept #12 without #18.

--

You received this message because you are subscribed to the Google Groups "Jenkins Developers" group.

To unsubscribe from this group and stop receiving emails from it, send an email to jenkinsci-de...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/jenkinsci-dev/78ac83c8-6290-41f9-98f9-7e977ec6004b%40googlegroups.com.

For more options, visit https://groups.google.com/d/optout.

--

Kohsuke Kawaguchi

[Liam Newman]

There's been quiet a bit of discussion offline about this

I've closed #18 as Kohsuke's objections to it make it a non-starter. 

I've instead opened

* https://github.com/jenkinsci/jep/pull/19 that restores BDFL delegates

* https://github.com/bitwiseman/jep/pull/1 proposed amendment to #19 that adds Governance meeting oversight of BDFL.

Comments welcome, PR's with proposed fixes preferred.  

[Liam Newman]

Updates:

• All proposed changes have been merged
• BDFL Delegates are fully described
• Governance meeting has oversight of BDFL
• Added JEP Template to the PR

https://github.com/jenkinsci/jep/pull/12 is now fully up-to-date and comments made so far have been addressed.

I believe JEP-1 is on the agenda for the next governance meeting.  Please review the PR and any propose fixes/changes now. 

[Kohsuke Kawaguchi]

Thanks!

To view this discussion on the web visit https://groups.google.com/d/msgid/jenkinsci-dev/adc45ded-07c6-4d7d-b1ef-2cac80165796%40googlegroups.com.

For more options, visit https://groups.google.com/d/optout.

--

Kohsuke Kawaguchi

[Liam Newman]

FYI

Jesse has proposed the adding an optional JIRA header.  

https://github.com/jenkinsci/jep/pull/21

It seems reasonable to me.  Unless there is strong opposition I'll merge this the main proposal on Wednesday. 

Thanks,

Liam Newman

[Robert Sandell]

Now that I've read Jesse's "JEP-0000: Switch Remoting/XStream blacklist to a whitelist" I'm thinking that maybe some form of "API summary" at the end for applicable JEPs would be nice to have. 

Just listing suggested deprecations, added methods, environment vars etc. previously mentioned in the text above, as it is somewhat cumbersome to do a quick ocular parse of actual changes in those lumps of text.

Thoughts?

/B

To unsubscribe from this group and stop receiving emails from it, send an email to jenkinsci-dev+unsubscribe@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/jenkinsci-dev/2b9ec3bb-96d0-46bb-8cc8-eaddbbfad3ae%40googlegroups.com.

For more options, visit https://groups.google.com/d/optout.

--

[Daniel Beck]

> On 31. Oct 2017, at 11:12, Robert Sandell <rsan...@cloudbees.com> wrote:
>
> Thoughts?
>

If it's relevant enough and not just implementation detail, it can always be added by the author even in the current format. But expecting a complete list of added/deprecated/removed APIs will just make proposing any change prohibitively cumbersome -- now you need the entire thing implemented (and not just as a prototype) before you can even ask for it to be considered. That's going to be a massive waste of time when, AFAIUI, one of the goals is making it possible to propose larger-scale changes without having every little detail mapped out (which is currently a prerequisite for having a PR discussion.

I'm pretty sure quite a bit of what's in Jesse's JEP exists there only because the implementation is basically already done. I think that's not a goal of the JEP process, and should not be.

[Jesse Glick]

On Tue, Oct 31, 2017 at 8:28 AM, Daniel Beck <m...@beckweb.net> wrote:
> quite a bit of what's in Jesse's JEP exists there only because the implementation is basically already done.

In this case, yes, excepting whatever might be turned up by further
testing or discussion.

> I think that's not a goal of the JEP process, and should not be.

Well, as I understand it you are expected to have at least a working
proof of concept in hand, but it is true that a finalized list of API
changes would not be expected in general.

If we need to see the aggregate impact of changes on an API, I would
suggest implementing this at a mechanical level, available in PR
builds, using tools like CLIRR. @andresrc experimented with this at
one point but it was not moved into production.

[Robert Sandell]

I was mostly thinking of it as an aid to the reader so that you don't have to do a ton of detective work when browsing the list of JEPs. Not having to also browse through potentially thousands of lines of code in one or more PRs and perhaps wiki docs etc. linked from the JEP.

In Jesse's case it would be a quick bullet list of what was already mentioned in the text, in other's it might be a summary added when the JEP is finalized and some others nothing.

/B

--
You received this message because you are subscribed to the Google Groups "Jenkins Developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email to jenkinsci-dev+unsubscribe@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/jenkinsci-dev/CANfRfr2z-B2cM3eL17deqnR4pawFvMR4affANhf3xaSxO5gGpg%40mail.gmail.com.

For more options, visit https://groups.google.com/d/optout.

[Kohsuke Kawaguchi]

On Tue, Oct 31, 2017 at 5:28 AM Daniel Beck <m...@beckweb.net> wrote:

> On 31. Oct 2017, at 11:12, Robert Sandell <rsan...@cloudbees.com> wrote:
>
> Thoughts?
>

If it's relevant enough and not just implementation detail, it can always be added by the author even in the current format. But expecting a complete list of added/deprecated/removed APIs will just make proposing any change prohibitively cumbersome -- now you need the entire thing implemented (and not just as a prototype) before you can even ask for it to be considered. That's going to be a massive waste of time when, AFAIUI, one of the goals is making it possible to propose larger-scale changes without having every little detail mapped out (which is currently a prerequisite for having a PR discussion.

Exactly!

I'm pretty sure quite a bit of what's in Jesse's JEP exists there only because the implementation is basically already done. I think that's not a goal of the JEP process, and should not be.

+1

 

--
You received this message because you are subscribed to the Google Groups "Jenkins Developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email to jenkinsci-de...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/jenkinsci-dev/C8261F02-D39F-4248-B8C3-549D12BC6D8E%40beckweb.net.

For more options, visit https://groups.google.com/d/optout.

--

Kohsuke Kawaguchi

[Liam Newman]

Proposed change to Add an option JIRA header has been merged. 

[Jesse Glick]

On Tue, Oct 31, 2017 at 11:43 AM, Robert Sandell <rsan...@cloudbees.com> wrote:
> Not having to
> also browse through potentially thousands of lines of code in one or more
> PRs

I fully agree that this can be painful; my suggestion was however that
the list of API changes be mechanically verified in a PR build. Do you
really trust that a textual JEP has been kept exactly up to date with
the API spec after dozens of commits? To be a good reviewer you would
need to double-check the API in the PRs anyway.

As a strawman proposal, suppose that you can optionally add a file to
the sources of Jenkins core or your plugin which specifies the
complete expected signature of all `public` and `protected` members in
the module, in a compact text file. A build-time process would verify
that the actual signature matches the expected signature. There would
also be a second file in the same format listing the signature as of
the last release (perhaps the release profile would enforce that the
two files are identical?); and a CI build would also verify that the
current signature is binary-compatible with the previous signature.

Thus if you proposed a PR which added to the API, you would need to
reflect those changes in the current signature file in order to get a
passing build, and PR reviewers could easily glance at this part of
the diff to confirm that the additions are reasonable. If you proposed
to remove an API (under dire circumstances!), you would delete that
member from the release signature file, and that would be quite
apparent in the PR.

AFAICT `clirr-maven-plugin` does not support such a workflow, but I
believe https://docs.oracle.com/javacomponents/sigtest-3-1/user-guide/part1.htm
would, and there are probably other suitable tools.

[Stephen Connolly]

animal sniffer could be adapted to assist, for example

--
You received this message because you are subscribed to the Google Groups "Jenkins Developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email to jenkinsci-dev+unsubscribe@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/jenkinsci-dev/CANfRfr3jndHrP0AeytpGmyBqMu55%3DB8yihfjCrWUr%3DP9oSdS8w%40mail.gmail.com.

[Robert Sandell]

I wasn't suggesting anything as comprehensive as an API spec, nor suggesting that it would be needed for the review process.

But as I've understood the JEP is that it should, among other things, serve as an archive for why something looks and behaves like it does.

So for people browsing that future archive, a quick list of what was added, removed or deprecated would be useful to quickly know if the JEP is going to be interesting read or not.

Something Like

Added

 Extension Point: CustomClassFilter

 System Property: hudson.remoting.ClassFilter

 redirect https://jenkins.io/redirect/class-filter/

Deprecated

 The crude blacklist extension API in Remoting (perhaps should be a bit more specific :) )

etc.

To view this discussion on the web visit https://groups.google.com/d/msgid/jenkinsci-dev/CA%2BnPnMyXpRKg%2BYF0mwVt6YjQE%2BHwHpMB0iP21zD7Q-zUCcsOPw%40mail.gmail.com.

For more options, visit https://groups.google.com/d/optout.

[Liam Newman]

Jesse has pointed out that the process does not say when or how JEPs are merged to master.  

There is discussion/proposals needed around what this should look like:

https://github.com/jenkinsci/jep/pull/25

[Daniel Beck]

> On 27. Oct 2017, at 21:03, Liam Newman <bitwi...@gmail.com> wrote:
>
> I believe JEP-1 is on the agenda for the next governance meeting. Please review the PR and any propose fixes/changes now.
>

A reminder: the meeting time is specified in UTC, which for the US and most of Europe at least means that the next meeting is now one hour earlier due to the recent end of DST.