spark-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Sean Owen <>
Subject Re: Design docs: consolidation and discoverability
Date Fri, 24 Apr 2015 19:57:50 GMT
Only catch there is it requires commit access to the repo. We need a
way for people who aren't committers to write and collaborate (for
point #1)

On Fri, Apr 24, 2015 at 3:56 PM, Punyashloka Biswal
<> wrote:
> Sandy, doesn't keeping (in-progress) design docs in Git satisfy the history
> requirement? Referring back to my Gradle example, it seems that
> is a really good way to see why the design doc evolved the way it did. When
> keeping the doc in Jira (presumably as an attachment) it's not easy to see
> what changed between successive versions of the doc.
> Punya
> On Fri, Apr 24, 2015 at 3:53 PM Sandy Ryza <> wrote:
>> I think there are maybe two separate things we're talking about?
>> 1. Design discussions and in-progress design docs.
>> My two cents are that JIRA is the best place for this.  It allows tracking
>> the progression of a design across multiple PRs and contributors.  A piece
>> of useful feedback that I've gotten in the past is to make design docs
>> immutable.  When updating them in response to feedback, post a new version
>> rather than editing the existing one.  This enables tracking the history of
>> a design and makes it possible to read comments about previous designs in
>> context.  Otherwise it's really difficult to understand why particular
>> approaches were chosen or abandoned.
>> 2. Completed design docs for features that we've implemented.
>> Perhaps less essential to project progress, but it would be really lovely
>> to have a central repository to all the projects design doc.  If anyone
>> wants to step up to maintain it, it would be cool to have a wiki page with
>> links to all the final design docs posted on JIRA.

To unsubscribe, e-mail:
For additional commands, e-mail:

View raw message