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