[Discuss] Design discussion for complex PRs

[Divij Vaidya <di...@gmail.com>]

Hey folks

We have recently had some big PR contributions (such as Go Client, Gremln
language semantics) which are complex enough to require a technical design
review by the community.

Currently, as a project, we don't seem to have a process or mechanism which
suggests that the contributors should provide an accompanying design doc to
their PRs. This leads to churn during the implementation/PR phase.

In light of the above, may I suggest the following:
1. Add a section in the "contributing to TinkerPop
<https://tinkerpop.apache.org/docs/current/dev/developer/#_contributing>"
page where contributors should be encouraged to submit a design document
(via JIRA) for complex changes/new features before their PR could be
considered for review.
2. Establish a process for design reviews (similar to other Kafka projects)
where a design should be approved by PMC votes.
3. Each design get's a PMC shepherd who would be intimately familiar with
the design and would be the primary code reviewer.

Examples of other Apache projects having a similar process:
1. Kafka's KIP:
https://cwiki.apache.org/confluence/display/kafka/kafka+improvement+proposals
2. Spark's SPIP: https://spark.apache.org/improvement-proposals.html

Thoughts?

Regards,
Divij Vaidya

Re: [Discuss] Design discussion for complex PRs

[Stephen Mallette <sp...@gmail.com>]

We have a mechanism for "proposals" described here:

https://github.com/apache/tinkerpop/blob/master/docs/src/dev/future/index.asciidoc#proposals

Norio Akagi submitted the first one with the "Equality, Equivalence,
Comparability and Orderability Semantics" document. My suggestion would be
to refine that further if needed and see a few more proposals land in there
before engineering in too much process. In the longer run, I dont believe
"proposals" should require PMC involvement or require specific VOTE
threads. TinkerPop tends to build consensus on design decisions easily here
and should continue to take advantage of that.

Divij (and others if interested), you might also look at the Cassandra
community with their Cassandra Enhancement Proposals (CEP):

https://cwiki.apache.org/confluence/pages/viewpage.action?pageId=95652201









On Thu, Feb 10, 2022 at 5:04 PM Divij Vaidya <di...@gmail.com>
wrote:

> Hey folks
>
> We have recently had some big PR contributions (such as Go Client, Gremln
> language semantics) which are complex enough to require a technical design
> review by the community.
>
> Currently, as a project, we don't seem to have a process or mechanism which
> suggests that the contributors should provide an accompanying design doc to
> their PRs. This leads to churn during the implementation/PR phase.
>
> In light of the above, may I suggest the following:
> 1. Add a section in the "contributing to TinkerPop
> <https://tinkerpop.apache.org/docs/current/dev/developer/#_contributing>"
> page where contributors should be encouraged to submit a design document
> (via JIRA) for complex changes/new features before their PR could be
> considered for review.
> 2. Establish a process for design reviews (similar to other Kafka projects)
> where a design should be approved by PMC votes.
> 3. Each design get's a PMC shepherd who would be intimately familiar with
> the design and would be the primary code reviewer.
>
> Examples of other Apache projects having a similar process:
> 1. Kafka's KIP:
>
> https://cwiki.apache.org/confluence/display/kafka/kafka+improvement+proposals
> 2. Spark's SPIP: https://spark.apache.org/improvement-proposals.html
>
> Thoughts?
>
> Regards,
> Divij Vaidya
>