spark-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Punyashloka Biswal <punya.bis...@gmail.com>
Subject Re: Design docs: consolidation and discoverability
Date Fri, 24 Apr 2015 23:42:16 GMT
Okay, I can understand wanting to keep Git history clean, and avoid
bottlenecking on committers. Is it reasonable to establish a convention of
having a label, component or (best of all) an issue type for issues that
are associated with design docs? For example, if we used the existing
"Brainstorming" issue type, and people put their design doc in the
description of the ticket, it would be relatively easy to figure out what
designs are in progress.

Given the push-back against design docs in Git or on the wiki and the
strong preference for keeping docs on ASF property, I'm a bit surprised
that all the existing design docs are on Google Docs. Perhaps Apache should
consider opening up parts of the wiki to a larger group, to better serve
this use case.

Punya

On Fri, Apr 24, 2015 at 5:01 PM Patrick Wendell <pwendell@gmail.com> wrote:

> 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.
> >> >>
> >>
>

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message