JEP: Modification of "Accepted" JEPs

[Liam Newman]

We recently had a pull request with a number of significant changes filed against JEP-201 which has already been "Accepted" (see the JEP workflow outlined in JEP-1).  

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

This poses a problem because the JEP workflow doesn't contain guidance for making/tracking significant changes to JEPs.  The intent of the process is for all major changes to land while the JEP is a "Draft". A JEP being "Accepted" means that a general consensus was reached regarding the design and scope of the component/area described by the JEP.  Once a JEP is marked "Final", the workflow specifically states that changes should be made by filing a new JEP and marking the old one as  "Superseded" when the new JEP is complete.

I would like to add the following clarifications to JEP-1:

1.  State specifically that all "significant changes" to a JEP should be completed before it is Accepted. This is pointed to in a number of places but may not be mentioned explicitly.
2. Define a "significant change" is any change that would modify the intent, scope, API, or overall behavior of the component.  I will provide some examples.
3. If "significant changes" are proposed to an "Accepted" JEP, it is be the responsibility of the Sponsor to communicate those changes on the mailing list and make sure that people have sufficient opportunity to review and comment before merging those changes.  A link to the thread should be included in the PR for the change and in the References section.
4. If there are strong objections to the proposed change, the Reviewer of the JEP may choose to return the JEP to a "Draft" state for continued discussion and re-review.

(Items 1 and 2 are both clarifications. Item 3 is a reiteration of the existing responsibilities of the JEP Sponsor in light of 1 and 2.  4 is a reiteration of the existing of responsibilities and powers of the JEP Review in light of 1 and 2.)

In the case of the above PR. it means that Ewelina would need to start a thread on the mailing list to discuss this change and give people time to review before we merge that change.  

What do people think of this?  An feedback or suggestions?

Thanks,

Liam Newman 

JEP-1 Sponsor

[Ewelina Wilkosz]

I'm perfectly ok with starting a discussion about proposed change

And in general I do not disagree with your proposal but I want to share my doubts... when we started working on Jenkins Configuration as Code we had an idea and then the idea has changed and I'm glad we put it all in one document. Now when I see a requirement "all 'significant changes' to a JEP should be completed before it is Accepted" it makes me worry that if I end up working on next JEP, for another project, I will be very careful and it will take ages to put it into "Accepted" (maybe it's not a problem). And then, like with JCasC, we learn while we implement it, we discover issues and things that we can't do the way we want to do. Do we have to discover all of that before "Accepting" JEP? That is the first thought that came into my mind.

Maybe it is exactly what you want and I can fully understand that. It just seems to me now that it is much more formal that I expected at the beginning.

Maybe it's because it's a new process, or I just missed some information, but then we should probably make sure that the information is there. We had a short discussion about that on Gitter lately, about purpose of JEP and which kind of things require JEP. You know that, a lot of people know, but many don't. Maybe it wouldn't be the worst idea to organise a Jenkins Online Meetup around JEP concept?

BR

Ewelina

[Joseph P]

Since this is only additions. And not a larger rewrite. It seems OK. Would it make sense to make a whole new JEP and link them two together? I don't think so. Plus it would be a really short JEP and somewhat out of context and you then spend more time on setting context.

Also if it were final you would still have to link them, right? Making a change to a final document.

/Joseph

[Carlos Sanchez]

I agree with Ewelina that "all 'significant changes' to a JEP should be completed before it is Accepted"  looks like a requirement that may hinder innovation and experimentation on areas that are not clear from the start. 

I'd rather see a review process that can return the JEP to a draft state for a v2 where people can discuss the new changes

--
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/6b84a0b5-a23b-44cf-80b3-faac982448ac%40googlegroups.com.

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

[Jesse Glick]

On Fri, Mar 23, 2018 at 8:11 AM, Carlos Sanchez <car...@apache.org> wrote:
> "all 'significant changes' to a JEP should be
> completed before it is Accepted" looks like a requirement that may hinder
> innovation and experimentation on areas that are not clear from the start.

To play devil’s advocate (I do not have strong feelings about this),
we should just make it comfortable enough to file follow-up JEPs that
this is normal practice. A JEP should stay as a Draft until there is a
clearly working implementation released. Once Accepted, there should
no eyebrows raised by filing another (initially Draft) JEP like “2018
refreshes to JEP-234 in light of mistakes made”. That can discuss any
compatibility issues that might affect early adopters of the original
version.

[Liam Newman]

This is a ton of great feedback, thanks!  

Ewelina,

JEPs have a number of purposes, but they are definitely _not_ meant to stifle innovation.  At minimum though, they are meant to provide a medium for building consensus on the design and implementation of major features/processes of the Jenkins (and related) project.  

Without JEP, contributors such as yourself, might do months of work only to have that work rejected or asked to be redesigned.  From the other side, the Project might get random contributors who ride in and want to have drop in some massive features without having discussed and reviewed with the rest of the project. 

I think the main misunderstanding (due to lack of clarity in JEP-1) is the idea that a JEP must be "Accepted" in order for contributors to have confidence in the value and validity of their work. That is absolutely not the case.

"Accepted" means that that Reviewer and Sponsor have looked at the JEP and agreed that _scoping and design_ are complete and have the consensus of the community, and that what remains is completing the (already well underway) implementation.  "Accepted" is a description of the technical state of the proposed component/feature/process.  "Accepted" is _not_ (and should not be viewed or used as) a "vote of confidence".  

Conversely, "Draft" is not a commentary on the likelihood that the JEP will eventually be "Accepted".  That can only determined by the Sponsors and the Reviewers based on discussion and feedback on the mailing list or other forums. "Draft" is _not_ (and should not be viewed as) an indicator of any lack of confidence in a proposal. 

> Now when I see a requirement 

> "all 'significant changes' to a JEP should be completed before it is Accepted"

> it makes me worry that if I end up working on next JEP, for another project, 

> I will be very careful and it will take ages to put it into "Accepted" (maybe it's

> not a problem). And then, like with JCasC, we learn while we implement it, 

> we discover issues and things that we can't do the way we want to do. 

> Do we have to discover all of that before "Accepting" JEP?

In short, yes, but as you might gather from my response above, that is not a bad thing. 

In the case of JEP-201, there has been no commentary it indicate that it lacks support, nor any doubt about the value of the work being done.  I think that the lack of clarity about the meaning of "Accepted" extends to the reviewers, so JEP-201 was marked as "Accepted" before the design was sufficiently complete.   But I also personally have no doubt that once the design is complete, JEP-201 will be "Accepted".

> Maybe it wouldn't be the worst idea to organize a Jenkins Online Meetup around JEP concept?

Yes, as noted above, I agree there is still misunderstanding about the JEP process.  I wouldn't have though to have JOM on this, but maybe we should.  It would be good to highlight that this process exists, talk about when and how to use it, and so on.  It would probably have to wait until May (April is looking pretty full already).  In the meanwhile, I still want to update JEP-1 to clarify 

Jesse, Thanks for responding.  You devil's advocate helped me craft the above response.  Also, do you feel we make it hard to file followup JEPs? 

Joseph, Carlos, I hope this response addresses your points.  If not please say so, and I'll respond specifically. 

Thanks,

-Liam

--
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/CANfRfr0F9z4sXKfZOGU%3D2vtveBt%2BdqReBy%2B4o5tpcwmNTKYEOQ%40mail.gmail.com.

[Andrew Bayer]

I think it’s more a cultural thing re comfortableness of followup JEPs - we need to have precedents and examples so that people will feel like oh, it’s ok that this stuff didn’t get into that JEP, we can just do a new JEP with it. Leaving proposals open for too long in order to make sure every possible tangentially related matter gets in is a path to stagnation. We’re far better off with more JEPs of potentially smaller size/scope, potentially amending earlier JEPs, than a small number of bloated ones, IMO.

A.

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

[Ewelina Wilkosz]

Thanks a lot for this extended answer Liam!

As I said I do not have any strong feelings/objections but I'm glad we have this discussion that hopefully will make things more clear :)

On Friday, March 23, 2018 at 12:47:52 AM UTC+1, Liam Newman wrote:

[Liam Newman]

Andrew,

That's an interesting point as well. The process is still relatively new, so it's not surprising that there's a learning curve and a need for more examples. JEPs with tighter focus will definitely move through the process more quickly, since they will require less discussion, design-time, implementation time, and consensus building.   JEP-200 was a good example of that tight focus and it still took some time.    

One way that Tyler has been addressing the scope considerations in relation the Jenkins Essentials is splitting the overall project into multiple JEPs.  JEP-300 covers the overall goals and high-level design, and delegates the internal design of those components to sub-JEPs that are being filed as work gets rolling.   I don't know if that means JEP-300 will be accepted sooner or will remain as draft, but it looks like that will be the case.  

It would be nice to have more JEPs filed to for a base of examples we can point people to, but I suspect we'll have to wait for that to grow organically over time.

-L. 

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

[Liam Newman]

Hello all,

I've attempted to synthesize the key points made here into a PR for JEP 1:

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

The scope of this change expanded a bit, but I think the result is clearer.

Please feel free to comment (or even better to commit edits directly). 

Thanks, 

Liam

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/CANfRfr0F9z4sXKfZOGU%3D2vtveBt%2BdqReBy%2B4o5tpcwmNTKYEOQ%40mail.gmail.com.
For more options, visit https://groups.google.com/d/optout.

--
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/CAA0qCNzNY4FZys4j7_bc07UmCkgaQf%3D0bMqn%2BDj_ogetDvTsGQ%40mail.gmail.com.

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

--
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.

[Joseph P]

Reading the updated JEP 1 sounds like PR 59 for JEP 201 would pass as minor changes which provides clarification.

Unless I am misinterpreting the intend of both pull requests 😆

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/CANfRfr0F9z4sXKfZOGU%3D2vtveBt%2BdqReBy%2B4o5tpcwmNTKYEOQ%40mail.gmail.com.
For more options, visit https://groups.google.com/d/optout.

--
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/CAA0qCNzNY4FZys4j7_bc07UmCkgaQf%3D0bMqn%2BDj_ogetDvTsGQ%40mail.gmail.com.

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

--
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.