spark-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Sean Owen <so...@cloudera.com>
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
<punya.biswal@gmail.com> wrote:
> Sandy, doesn't keeping (in-progress) design docs in Git satisfy the history
> requirement? Referring back to my Gradle example, it seems that
> https://github.com/gradle/gradle/commits/master/design-docs/build-comparison.md
> 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 <sandy.ryza@cloudera.com> 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: dev-unsubscribe@spark.apache.org
For additional commands, e-mail: dev-help@spark.apache.org


Mime
View raw message