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

DEP: The Dat Enhancement Proposal Process (for Draft status) #2

Merged
merged 18 commits into from Feb 7, 2018

Conversation

Projects
None yet
4 participants
@bnewbold
Contributor

bnewbold commented Jan 11, 2018

View it rendered here

Also rendered README and template.

This first DEP is now ready for review. I'm submitting it for Draft status, with the hope that it stabilizes to Active within a couple months after a couple other DEPs go through the process.

I believe I pulled in all the decisions from today's WG meeting (notes).

While we mentioned a two week review period during the meeting, I remembered that that's a maximum, so if everybody likes what they see here we could merge-as-draft sooner (though not less than ~3 days to give everybody time to read). Also totally fine to wait two weeks until the next meeting.

proposal and work out all the details. This step isn't necessary, however: a
proposer does not need to be a developer.
* If consensus seems to have emerged (for or against the proposal), a team
member will assign an DEP number, update the status, and merge the PR.

This comment has been minimized.

@pfrazee

pfrazee Jan 11, 2018

Member

The BEPs system assigns numbers to some drafts and puts them on their website. I think that's a good idea, because there may be DEPs that we want to keep as a draft for long & ongoing discussion, and having a number would help with that. The proposed process suggests that DEPs are only given a number and merged when consensus is reached.

I propose we separate the process for "publishing drafts" and "resolving drafts." Draft-publish will get the PR merged and a number assigned, but leave the status as Draft. Draft-resolution will then modify the status of a published draft to Active or Closed. Both steps (publish & resolution) will require consensus on the action.

This comment has been minimized.

@bnewbold

bnewbold Jan 16, 2018

Contributor

Sure, I think that's reasonable. I think we can also have a lower bar for edits to a draft (eg, allow larger changes to the draft in response to discussion or implementation) than something that has been accepted.

Who are "core developers"? What is the specific decision making process for
accepting or rejecting a given DEP? Optimistically, it would be clear from
reading a PR discussion thread whether "consensus" has been reached or not, but
this might be ambiguous or intimidating to first-time contributors.

This comment has been minimized.

@pfrazee

pfrazee Jan 11, 2018

Member

I propose we create a process whereby we establish "repo admins." These admins would be re-evaluated every N months (I propose 6), and being selected as an admin means committing to involvement for the full N months. At the end of the period, new "repo admins" are selected by unanimous consent of the previous period's admins, and that may mean no change in the admins. I would suggest one admin per organization which has an interest in Dat (which at this point would be Code for Science and Society, Blue Link Labs, and the Internet Archive) but there's no reason to follow that exactly.

For decision-making, I would also suggest that any decision requires unanimous consent from the repo admins, with an informal requirement that we factor community feedback in the decision.

This comment has been minimized.

@bnewbold

bnewbold Jan 16, 2018

Contributor

This is a reasonable proposal. I think I want to research this governance aspect of the prospect a bit more... I will revise the other aspects, and maybe we can merge this as a draft to separate the desire to move ahead from committing to all the governance details?

This comment has been minimized.

@tristanls

tristanls Jan 16, 2018

This article had a lot of very specific recommendations/proposals for "building cooperation into the system" that may be worth considering: https://medium.com/@nayafia/the-problem-with-voting-8cff39f771e8

This comment has been minimized.

@joehand

joehand Jan 16, 2018

Member

Thanks @tristanls! I linked that in the IRC as well, very helpful!

(seems like we could rely on blog posts) an "normative". This might be helpful
for documenting things like peer discovery methods, which have intentially not
been specified as part of the formal spec (to make it clear that there is no
single "right way" to do discovery), but they should be documented somewhere.

This comment has been minimized.

@pfrazee

pfrazee Jan 11, 2018

Member

I think "normative" would be a good category to have, for the reasons you say.

This comment has been minimized.

@bnewbold

bnewbold Jan 16, 2018

Contributor

I didn't know how the word was defined when I wrote that. From Wikipedia:

Normative = prescriptive = how to comply
Informative = descriptive = help with conceptual understanding

I don't think that's the axis we're talking about here... more formal/informal? I think "Standard" should be more formal and strict ("if you're not doing it this way, You're Doing It Wrong"), and what we're looking for with a third category is "here's what some folks are doing and it works for them".

I fear "Normative" is overloaded. "Informative" probably works. Other similar words: convention, custom, descriptive

I think I like "Descriptive" best so far.

This comment has been minimized.

@pfrazee

pfrazee Jan 16, 2018

Member

Informative or Descriptive seem good to me

Some communities eventually subsume the core protocol specification itself into
the DEP process (for example, the official Bittorrent protocol was documented
in a "BEP"). Should dat do this? Or rely on the current (and possibly future)
Dat whitepaper?

This comment has been minimized.

@pfrazee

pfrazee Jan 11, 2018

Member

I vote that we put the protocol documentation into the DEP process.

This comment has been minimized.

@bnewbold

bnewbold Jan 16, 2018

Contributor

Thinking outloud:
I'm not sure whether we should do this as one big document, or split it into components (basically along the node module abstraction layers: sleep, hypercore, hyperdb, discovery). I think the later... and then either have a "how it all fits together" DEP (maybe a "normative" one showing one way it could be done?), or rely on the whitepaper, or hand wave that it's self obvious.
I guess we don't actually need to show how a client would work all together in the specification, and should leave that as undefined as possible?

This comment has been minimized.

@joehand

joehand Jan 16, 2018

Member

I guess we don't actually need to show how a client would work all together in the specification, and should leave that as undefined as possible?

Seems like maybe this would fit in better at docs.datproject.org. It can be more hand waving so its easier to keep updated. Otherwise we may have to update with each spec change.

I think the key is that implementation details need to always be 100% up to date. More general, this is how Dat works don't need describe all the details.

This comment has been minimized.

@pfrazee

pfrazee Jan 16, 2018

Member

I like the proposal of having DEPs for each abstraction layer and then an Informative/Descriptive on how they integrate. I think it does need to be a DEP though, because it's pretty important information for somebody making a full implementation. What I'd expect is that the "Fit-together DEP" would give an overview of the different pieces and describe how they interact, which would make it a very useful highlevel description of the protocol. Isolating the subDEPs would help them be specced more completely, and avoid enormous and unwieldly DEP docs.

@pfrazee

This comment has been minimized.

Member

pfrazee commented Jan 11, 2018

Nice start @bnewbold

@bnewbold

This comment has been minimized.

Contributor

bnewbold commented Jan 20, 2018

This round of edits was more divergent (more ideas, more text) than I was hoping. Will probably do a more convergent (polish, simplify) edit and then "submit" this weekend so it has a couple days to sit before our working group meeting next Wednesday.

README.md Outdated
Accepted proposals will be viewable at [datprotocol.com](https://datprotocol.com).
New (draft) proposals and discussion can be viewed on [github][github-deps]
under "issues" and "pull-requests".

This comment has been minimized.

@joehand

joehand Jan 24, 2018

Member

All DEP proposal discussion should happen in PRs so we don't get discussion fractured.

The Dat protocol is still a living standard. A transparent process is needed
for community members to understand what changes are in the pipeline and how
new ideas might come to fruition.

This comment has been minimized.

@joehand

joehand Jan 24, 2018

Member

Preparing to handle protocol version changes/breaks is also a primary motivation =). Should be mentioned upfront.

This comment has been minimized.

@bnewbold

bnewbold Jan 25, 2018

Contributor

Almost forgot this!

Draft to Active. At this time a final review will take place, with the
outcome being that a prosal stays a Draft or is Active. It's also possible
for a Draft to be Closed (usuall by a specific PR to propose this). This
review period is shorter (**2 weeks maximum**), as the relevant reviewers

This comment has been minimized.

@joehand

joehand Jan 24, 2018

Member

Should we also make sure this includes a discussion at the next working group?

This comment has been minimized.

@bnewbold

bnewbold Jan 24, 2018

Contributor

That sounds reasonable. I included a time-bound so PRs wouldn't get "stuck", but it could be a bit longer to ensure there is time for a WG meeting. I can imagine that, at least to start, a common workflow is going to be the WG itself discussing and proposing that a DEP be stabilized to "Active" anyways, which would make the scheduling easier.

I am unsure how much WG-internals should laid out in this DEP... but I don't want to just kick those decisions down the road either.

# Decision Making Process
[power]: #power
There exists a Protocol Working Group (WG) which makes DEP status decisions.

This comment has been minimized.

@bnewbold bnewbold changed the title from WIP: meta-DEP to DEP: The Dat Enhancement Proposal Process (for Draft status) Jan 25, 2018

@bnewbold

This comment has been minimized.

Contributor

bnewbold commented Jan 25, 2018

While writing this, I thought of a better way to describe the difference between the expectations about "Draft"/"Active" here (and in practice with Rust, and I think Python) vs. current practice with Bittorrent BEPs: whether the proposals lead implementation, or the implementation leads proposals and standards. W3C is maybe a good example of both: sometimes (HTML5?) the standards process guides implementation (browsers), but very often the opposite is true (standards process is playing catch up).

Obviously we've got a bunch of implementation running around already, but I think it could be really helpful (and realistic) for proposals and documentation to lead implementation.

[Paul Frazee](https://github.com/pfrazee),
[Mathias Buus](https://github.com/mafintosh),
[Karissa McKelvey](https://github.com/karissa),
[Joe Hand](https://github.com/karissa),

This comment has been minimized.

[Mathias Buus](https://github.com/mafintosh),
[Karissa McKelvey](https://github.com/karissa),
[Joe Hand](https://github.com/karissa),
[Danielle Robinson](#),

This comment has been minimized.

@joehand

This comment has been minimized.

Member

joehand commented Jan 30, 2018

Looks great, thanks for updating this!

fix author github URLs
Thanks joehand!

@joehand joehand self-requested a review Feb 5, 2018

@joehand

joehand approved these changes Feb 5, 2018

Looks ready to merge into Draft!

@pfrazee

This comment has been minimized.

Member

pfrazee commented Feb 5, 2018

I'm happy with this DEP's state.

@pfrazee

pfrazee approved these changes Feb 5, 2018

@pfrazee pfrazee merged commit 69ac461 into datprotocol:master Feb 7, 2018

@bnewbold bnewbold deleted the bnewbold:meta-dep branch Feb 7, 2018

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment