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 <c...@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 <so...@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.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
