spark-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Patrick Wendell <pwend...@gmail.com>
Subject Re: Design docs: consolidation and discoverability
Date Fri, 24 Apr 2015 21:01:48 GMT
Using our ASF git repository as a working area for design docs, it
seems potentially concerning to me. It's difficult process wise
because all commits need to go through committers and also, we'd
pollute our git history a lot with random incremental design updates.

The git history is used a lot by downstream packagers, us during our
QA process, etc... we really try to keep it oriented around code
patches:

https://git-wip-us.apache.org/repos/asf?p=spark.git;a=shortlog

Committing a polished design doc along with a feature, maybe that's
something we could consider. But I still think JIRA is the best
location for these docs, consistent with what most other ASF projects
do that I know.

On Fri, Apr 24, 2015 at 1:19 PM, Cody Koeninger <cody@koeninger.org> wrote:
> Why can't pull requests be used for design docs in Git if people who aren't
> committers want to contribute changes (as opposed to just comments)?
>
> On Fri, Apr 24, 2015 at 2:57 PM, Sean Owen <sowen@cloudera.com> wrote:
>
>> 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