Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Comments on process and steering committee documents #81

Closed
5 of 11 tasks
dschult opened this issue Mar 2, 2021 · 5 comments
Closed
5 of 11 tasks

Comments on process and steering committee documents #81

dschult opened this issue Mar 2, 2021 · 5 comments
Assignees

Comments

@dschult
Copy link

dschult commented Mar 2, 2021

NOTE from Jarrod:  The checked off items are addressed in PR #83.  The non-checked off items have inline comments.

I like the turn toward decision points rather than stages.
It makes the process more fluid and the changes are clear.

Purpose-and-process document:

  • Description section seems good. The goals are clear and justified.

  • Implementation section seems to have two goals. Maybe split?

    1. Show people how to get their idea started and through the process.
    2. Lay out each decision point and the people involved in each decision.
      Two sections:
    • Implementation section:
      Start with "A SPEC passes through..."

    • How to get started:
      Start with "A good SPEC proposal focuses..." up to 1, 2, 3.
      Then "Before a proposed SPEC can be accepted..." and up
      to "...a pull request against the SPEC repository."

  • Add "The Steering Committee then considers the SPEC as presented
    in the pull request."

  • Remove the first paragraph of Implementation:

    • we don't know who will drive the SPECs
    • the focus on the "accept" decision point is too strong and appears below.
  • accept decision seems good.

  • endorse decision need some changes I think:

    • Remove the 3rd sentence: only discouraging and we don't know if true.
    • "Most specs..." but we don't know whether most will do this or not.
      Maybe "The intent is that most SPECs..."
    • If two core projects are required for acceptance and two are required for
      endorsement, then endorsement will likely occur right after acceptance.

"""
Acceptance requires contributors from at least two core projects who are interested in developing the SPEC and championing it. That doesn't mean two Core Projects will endorse it or that it is even ready for any Core Projects to endorse it. Maybe the SPECs will all be completely obvious and the first draft will be acceptable, but I doubt that. I drafted SPEC 0 and I am not sure I would vote for NetworkX to endorse it as it is. It isn't even what I personally would want or recommend. I am assuming that before it is ready we will need to have several discussions both inside NetworkX and with other projects. However, I am interested in the community coming to some sort of agreement on this issue and am willing to engage in the discussion, listen to feedback, and update the SPEC. Once that conversation settles and the draft SPEC is sufficiently revised, the NetworkX core developers would need to vote. At that point, I only have one vote. We could just remove the draft status and accept stage. I could develop the SPEC somewhere else. And once a number of projects agree to "endorse" it, I could submit a PR to the SPEC repo. But then I will need to figure out somewhere else to work on it. Or we would have to have everyone work on my PR. That would mean people would need to submit PRs to my branch and we wouldn't have any obvious mechanism to determine how interest there is for my proposed SPEC. Maybe that would work.
"""
''' That makes sense. The proposals can come from Core project contributors who aren't Core developers of those projects. And, as you say -- proposing it doesn't mean you like everything about it yet -- just that it'd be good to have a spec about it.
'''

- [ ] The word "recommended" appears here and it is not clear what it
  means, who makes that decision and what the impact is.

"""
Recommend isn't a decision. It happens automatically when two Core Projects decide to endorse a SPEC. We could call it endorsed, but then the language gets slightly abused. I could say NetworkX endorsed the SPEC, but the SPEC isn't endorsed until a second Core Project endorses it. We could require just one Core Project to endorse a SPEC, but then where is the coordination between projects? I am not sure "recommend" it the correct word. The main thing that changes technically is that a SPEC with two endorsements has it's draft status removed. I struggled with the language, so any suggestions are welcome. The basic idea is I needed a word to describe the SPEC document before it is accepted (I choose proposed). I needed a word to refer to a SPEC document after it is accepted by the steering committee, but before it is endorsed by two core projects (I choose draft). I needed a word to describe the SPEC document after it is endorsed by two Core Projects (I choose recommended).

We could call a SPEC that has been "endorsed" by two Core Projects "endorsed." But that doesn't seem ideal to me. Thoughts?
"""
'''
Maybe here is where we can use the word "approve". The projects endorse the Draft SPEC, and once 2 Core projects endorse it, the Draft SPEC is "approved" and becomes a SPEC. Every SPEC is recommended, but each Core Project can adopt it as they wish.

Here is a related point or process: who notices that 2 projects endorse the Draft SPEC? Is this up to the Steering Committee? Some administrator should be tasked with noticing and making a PR that shifts it from Draft SPEC to SPEC. No decision is required, but I think we still need some way to "make it so".
'''

- [ ] Do projects other than Core projects participate in this?  Could a non-Core
  project propose a SPEC? As written, they need to get Core Project people
  on board before it gets accepted. After that it is really just Core projects?

"""
Any project can participate. But only Core Projects can "endorse." The idea was to explicitly require SPECs to get some input from the Core Projects. If we open it up to any project, we will need to come up with a more elaborate mechanism for registering projects. It also isn't clear to me how SPECs would be compared. For example, what if there is a SPEC that is "endorsed" by two 1-person projects that are very niche? Or a SPEC proposed by a corporation by using two projects they control to push a technology they are financially invested in? How would we distinguish them from a SPEC endorsed by NumPy and SciPy?

It seem to me that opening recommendations up to any project in the ecosystem will require a ton more thought and process. It would also require getting a lot more input before we begin. I want to start with something small and manageable. Once the process is up and running, the steering committee can revisit this.
"""

 - [ ] We need a way that projects "endorse" a SPEC. Perhaps they create a PR
  adding text to the SPEC that they endorse it?

"""
They make a PR and add there project name to the endorse-by field. This is explained in the Core Project document under the heading How does a Core Project endorse a SPEC?
"""
'''
I agree. Let's keep it simple. If a project wants to be involved they should ask to become a Core project.
'''

- [ ] "Once two projects endorse the SPEC then further changes require the
  approval of all endorsed projects."  How is such approval indicated?
  Who represents the projects in these decisions? Can the endorsement
  of one project be removed by the other projects if the one stops responding?

"""
How approval is handled will depend on the project and the nature of the change. The Core Projects should all have a core developer team responsible for making decisions. If they make a decision, they will need to do it publicly. For example on a mailing list or something. Core Projects can't remove other Core Projects endorsements. Only the Core Project itself or the Steering Committee can. This is explained in Core Project document under the heading How do you remove a project? Being a Core Project requires they participate in the process. If a Core Project stops participating, the Steering Committee should remove the project from the Core Project list. That means the project would be removed from the list of Core Projects and from all SPEC endorsed-by fields. If a SPEC doesn't have two endorsements, it is automatically reverted to draft status (i.e., it is no longer "recommended").
"""
'''
Nice -- I hadn't thought of this before. The SPEC can be demoted if projects remove their endorsement. That really means we need someone to pay attention and make a change when a Draft SPEC becomes a SPEC and when it gets demoted to a Draft SPEC again.
'''

  • adopt decision seems good -- though it doesn't seem much different from
    endorsing. The difference is that the project implements the
    Ecosystem Adoption section. (??)

"""
Endorse means that two Core Projects have vetted and approve the SPEC. The idea being that I wanted something more than a place any random idea could be added. Having a SPEC endorsed doesn't actually require any projects to adopt it. Although, the intention is if a Core Project endorses a SPEC that the also would adopt it. However, that may not always make sense. For example, NumPy could endorse a SPEC describing how to use NumPy and SciPy together; but since NumPy doesn't use SciPy, I am not sure what NumPy adopting it would mean.
""""
''' This makes sense.'''

Steering Committee document:

  • I like the description section's bullets. I think that lays it out clearly.
    The last sentence could just be "... which SPECS are endorsed or adopted."
    (that process is described in the other document so don't need to rehash here)

"""
I removed the sentence. It was left over from an earlier revision.
"""

  • The footnote [^accept] lays out what is appropriate -- so rename?
    And perhaps these guidelines should be brought into the main text.
    It should be identical to the points from the process document.
    This wording is good -- perhaps move it to the process document too?

"""
That text is copied verbatim from the process document. I repeated it to make it easier to find. I will see if there is a way to link to the relevant text in the process document instead.
"""
''' You could just change the name of the footnote to [^approval] instead of [^accept]. The wording is fine.'''

  • The vote "within ten days" is not clear. "ten days" after what?

"""
I added a note to the doc. I will bring it up with the steering committee to see how they want to handle voting. Do they want to @mention the steering committee on a PR? Do they want to send an email to their private mailing list? Or do they want to use another tool for voting?
"""

  • Should voting on membership be included in the 2/3 majority section?

"""
Yes, that is what I intended. Are you suggesting that it isn't clear what I intended or that membership voting should be handled differently. The official list of members is the steering committee doc, so updating the membership is currently the same as changing anything about the process docs including changing the steering committee membership or list of Core Projects.

Thoughts/suggestions?
"""
'''I was wanting more clarity about the voting process. Perhaps add the phrase "(by consensus or 2/3 vote)" to the text: "If the Steering Committee decides to admit a new member and that person agrees, ...". So that it reads: "If the Steering Committee decides to admit a new member (by consensus or 2/3 vote) and that person agrees, ...". A similar phrase could be for removal, though that would not be consensus unless the person wishes to be removed which is already handled. So it'd be shorter here:
"If a member wishes to resign or if the Steering Committee decides to remove a member (by 2/3 vote), then ...". Maybe all this is too much harping on the 2/3 vote rule... So long as it is clear before the committee has to do this kind of thing, we're fine.
'''

@rossbar
Copy link
Member

rossbar commented Mar 10, 2021

Recommend isn't a decision. It happens automatically when two Core Projects decide to endorse a SPEC....

This is related to the point that I raised in the previous comment as well. It gets a little confusing (esp. in the flowchart) whether the "propose-draft-recommend" arrows represent actions or the status of the document in relation to the various decision points. If it's the latter, i.e. some sort of formal document status, then I think "proposed", "accepted", and "endorsed" make sense, though that circles back around to the confusion related to "accepted" sounding like it's the end of the spec process, instead of the beginning.

@dschult
Copy link
Author

dschult commented Mar 11, 2021

Here an option just to muddy the waters further:

The states: Proposal -> Draft SPEC -> SPEC
The actions: Accept and Endorse.
(Do we need to describe the "adopt" action? That's really separate from this process, but maybe not -- in which case Accept, Endorse and Adopt?)

So a story of the process could be something like:
We submitted a Proposal to the SPEC steering committee and they asked us to refine it and so we did and we worked with other groups and finally the Steering Committee Accepted it. So it became a Draft SPEC -- which sounded much more official than just a Proposal. Then we worked with the Core Projects to get them to endorse the Draft SPEC. It took a while, but finally one Core Project officially endorsed the Draft SPEC. Shortly after that 2 more Endorsed it as well (we only needed one more, but the more endorsements the better). So now it is officially a SPEC. [without "Adopt": 4 Core projects have adopted it and lots of non-core projects use it too.] [with "Adopt": 4 Core projects have officially Adopted it, others use it unofficially and there are a bunch of non-Core projects who use it and have essentially adopted it but they aren't allowed to officially adopt it.]

:}

I think a PEP is called a PEP before it becomes official. But proposal is part of the PEP name. SPEC could be a word reserved only for proposals that have been accepted and endorsed by 2 or more Core Projects.

@jarrodmillman
Copy link
Member

jarrodmillman commented Mar 11, 2021

I don't have much more time to revise these documents and I worry we are spending too much time trying to come up with right words and process without any experience with how it works in practice. I just merged PR #83 will leave this issue open.

Once we finish recruiting the steering committee, get the core projects to sign on, and have some experience trying to follow the process as outlined, maybe someone will have a better idea and can suggest a better process or at least come up with better words to describe the process.

@dschult
Copy link
Author

dschult commented Mar 11, 2021

I think we are definitely into wordsmything ... Let's merge the PR and NOT leave this issue open. :}

@jarrodmillman
Copy link
Member

@dschult , @rossbar I am closing this issue, but I created issue #84 to continue the language discussion. I am not expecting to act quickly on that issue, but hopefully we can get more discussion there. Hopefully, someone will propose better language or a cleaner (and maybe simpler?) description of the process. I didn't try to capture your concerns or questions, so it would be great if you could add some comments to the new issue when you have time. Thanks!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

3 participants