-
Notifications
You must be signed in to change notification settings - Fork 45
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
Comments
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. |
Here an option just to muddy the waters further: The states: Proposal -> Draft SPEC -> SPEC So a story of the process could be something like: :} 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. |
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. |
I think we are definitely into wordsmything ... Let's merge the PR and NOT leave this issue open. :} |
@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! |
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?
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:
accept decision seems good.
endorse decision need some changes I think:
Maybe "The intent is that most SPECs..."
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.
'''
"""
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".
'''
"""
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.
"""
"""
They make a PR and add there project name to the
endorse-by
field. This is explained in the Core Project document under the headingHow 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.
'''
"""
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 SPECendorsed-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.
'''
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:
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.
"""
[^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.'''
"""
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?
"""
"""
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.
'''
The text was updated successfully, but these errors were encountered: