Reads very well, nice work Braden! I was going to mention adding the creation of a topic branch for completeness, but Ian, Max, and you have already hashed that out.
I would vote to create a "Contributor" section under "Guides." If Marcel feels there's importance in defining roles, then that's where that documentation can go as well. Another useful article would be GitHub Pull Requests (sending and managing), since Apache is a read-only mirror. Not sure how useful it is, but my PhoneGap Day 2012 presentation "Contributing to Apache Cordova" [1] added some definitions about Contributor and Committer. [1] http://michaelbrooks.ca/deck/contributing-to-cordova/2012-08-21-adobe-web-summit/index.html Michael On Tue, Mar 12, 2013 at 1:52 PM, Marcel Kinard <cmarc...@gmail.com> wrote: > From a conceptual perspective, one of the things that seems a bit > convulted across the project is that there aren't clear documentation > buckets for the different roles: Cordova committer, Cordova contributor, > Cordova user. There is some really good content, but it's a bit fractured > across the cordova-docs.git, README.md in other repos, wiki, etc. Maybe I > just look at things through role-colored glasses. > > Your googledrive doc looks like great content for the Cordova committer. > This suggestion may be growing the scope from what you intended, but would > it make sense to build a "Cordova committer" bucket and start to > consolidate docs for that role in that place starting with this one, such > as moving similar content out of the wiki, etc? > > What you've written here I would categorize as process or governance. > Another question I'd ask is if the process/governance docs should go in the > source code repo or someplace else? Assuming they will be branched and > version-tagged similar to the code, that puts them the same timeline as the > code. But I don't typically think of branching and snapshotting > process/governance docs and keeping around old copies, because > process/governance is constantly evolving and generally new > process/governance can be mixed with old code because it is > infrastructure-related, instead of function-in-code related. So perhaps the > question here is (assuming this md goes into git) should that git not get > branched/snapshot'd, and instead publish only HEAD, because you always use > the process/governance described in HEAD? In which case, a wiki is not a > bad versioning model, assuming you can render what you want. > > -- Marcel Kinard > > On Mar 11, 2013, at 7:35 PM, Braden Shepherdson <bra...@chromium.org> > wrote: > > > I wrote up the new git workflows into a doc intended for inclusion in the > > Cordova Documentation (it provides much nicer formatting than the wiki). > > You can check it out here: > > > > > https://googledrive.com/host/0B8sLcyOAEX-XUHAxNXhISE5rTTg/guide_contributing_index.md.html > > > > Please let me know if you spot any problems or have any questions. If > > people like the idea of a contributor entry in the Guide, I'll commit > this > > into edge. > > > > Braden > >
