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.bis...@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.r...@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-unsubscr...@spark.apache.org
For additional commands, e-mail: dev-h...@spark.apache.org

Reply via email to