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. -Sandy On Fri, Apr 24, 2015 at 12:01 PM, Punyashloka Biswal <punya.bis...@gmail.com > wrote: > The Gradle dev team keep their design documents *checked into* their Git > repository -- see > > https://github.com/gradle/gradle/blob/master/design-docs/build-comparison.md > for example. The advantages I see to their approach are: > > - design docs stay on ASF property (since Github is synced to the > Apache-run Git repository) > - design docs have a lifetime across PRs, but can still be modified and > commented on through the mechanism of PRs > - keeping a central location helps people to find good role models and > converge on conventions > > Sean, I find it hard to use the central Jira as a jumping-off point for > understanding ongoing design work because a tiny fraction of the tickets > actually relate to design docs, and it's not easy from the outside to > figure out which ones are relevant. > > Punya > > On Fri, Apr 24, 2015 at 2:49 PM Sean Owen <so...@cloudera.com> wrote: > > > I think it's OK to have design discussions on github, as emails go to > > ASF lists. After all, loads of PR discussions happen there. It's easy > > for anyone to follow. > > > > I also would rather just discuss on Github, except for all that noise. > > > > It's not great to put discussions in something like Google Docs > > actually; the resulting doc needs to be pasted back to JIRA promptly > > if so. I suppose it's still better than a private conversation or not > > talking at all, but the principle is that one should be able to access > > any substantive decision or conversation by being tuned in to only the > > project systems of record -- mailing list, JIRA. > > > > > > > > On Fri, Apr 24, 2015 at 2:30 PM, Reynold Xin <r...@databricks.com> > wrote: > > > I'd love to see more design discussions consolidated in a single place > as > > > well. That said, there are many practical challenges to overcome. Some > of > > > them are out of our control: > > > > > > 1. For large features, it is fairly common to open a PR for discussion, > > > close the PR taking some feedback into account, and reopen another one. > > You > > > sort of lose the discussions that way. > > > > > > 2. With the way Jenkins is setup currently, Jenkins testing introduces > a > > lot > > > of noise to GitHub pull requests, making it hard to differentiate > > legitimate > > > comments from noise. This is unfortunately due to the fact that ASF > won't > > > allow our Jenkins bot to have API privilege to post messages. > > > > > > 3. The Apache Way is that all development discussions need to happen on > > ASF > > > property, i.e. dev lists and JIRA. As a result, technically we are not > > > allowed to have development discussions on GitHub. > > > > > > > > > On Fri, Apr 24, 2015 at 7:09 AM, Cody Koeninger <c...@koeninger.org> > > wrote: > > >> > > >> My 2 cents - I'd rather see design docs in github pull requests (using > > >> plain text / markdown). That doesn't require changing access or > adding > > >> people, and github PRs already allow for conversation / email > > >> notifications. > > >> > > >> Conversation is already split between jira and github PRs. Having a > > third > > >> stream of conversation in Google Docs just leads to things being > > ignored. > > >> > > >> On Fri, Apr 24, 2015 at 7:21 AM, Sean Owen <so...@cloudera.com> > wrote: > > >> > > >> > That would require giving wiki access to everyone or manually adding > > >> > people > > >> > any time they make a doc. > > >> > > > >> > I don't see how this helps though. They're still docs on the > internet > > >> > and > > >> > they're still linked from the central project JIRA, which is what > you > > >> > should follow. > > >> > On Apr 24, 2015 8:14 AM, "Punyashloka Biswal" < > > punya.bis...@gmail.com> > > >> > wrote: > > >> > > > >> > > Dear Spark devs, > > >> > > > > >> > > Right now, design docs are stored on Google docs and linked from > > >> > > tickets. > > >> > > For someone new to the project, it's hard to figure out what > > subjects > > >> > > are > > >> > > being discussed, what organization to follow for new feature > > >> > > proposals, > > >> > > etc. > > >> > > > > >> > > Would it make sense to consolidate future design docs in either a > > >> > > designated area on the Apache Confluence Wiki, or on GitHub's Wiki > > >> > > pages? > > >> > > If people have a strong preference to keep the design docs on > Google > > >> > Docs, > > >> > > then could we have a top-level page on the confluence wiki that > > lists > > >> > > all > > >> > > active and archived design docs? > > >> > > > > >> > > Punya > > >> > > > > >> > > > > > > > > > >
