I actually don't totally see why we can't use Google Docs provided it is clearly discoverable from the JIRA. It was my understanding that many projects do this. Maybe not (?).
If it's a matter of maintaining public record on ASF infrastructure, perhaps we can just automate that if an issue is closed we capture the doc content and attach it to the JIRA as a PDF. My sense is that in general the ASF infrastructure policy is becoming more and more lenient with regards to using third party services, provided the are broadly accessible (such as a public google doc) and can be definitively archived on ASF controlled storage. - Patrick On Fri, Apr 24, 2015 at 4:57 PM, Sean Owen <so...@cloudera.com> wrote: > I know I recently used Google Docs from a JIRA, so am guilty as > charged. I don't think there are a lot of design docs in general, but > the ones I've seen have simply pushed docs to a JIRA. (I did the same, > mirroring PDFs of the Google Doc.) I don't think this is hard to > follow. > > I think you can do what you like: make a JIRA and attach files. Make a > WIP PR and attach your notes. Make a Google Doc if you're feeling > transgressive. > > I don't see much of a problem to solve here. In practice there are > plenty of workable options, all of which are mainstream, and so I do > not see an argument that somehow this is solved by letting people make > wikis. > > On Fri, Apr 24, 2015 at 7:42 PM, Punyashloka Biswal > <punya.bis...@gmail.com> wrote: >> 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 <pwend...@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 <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
