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
