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