- From: Dave Jensen <david@jensen47.com>
- Date: Tue, 28 Apr 2015 15:07:25 -0700
- To: T Guild <ted@w3.org>
- Cc: Paul Boyes <pb@opencar.com>, Kazuyuki Ashimura <ashimura@w3.org>, public-automotive <public-automotive@w3.org>
- Message-ID: <CA+JJkjqsL_frF8OXfz8DkdRCDOV412a9wF5Y4sq7nX-TnxKa4w@mail.gmail.com>
After reviewing the contents of w3c/automotive-bg here's what I think needs to be addressed with regard to the repo. Hopefully, this is not overkill… 1. Layout - Where do all of the files live. - What do the files/directories mean. 2. A better README - Right now, when you visit the repo page, you have no idea where to start 3. Contribution guidelines - How to make a change, compile the HTML output, etc. - Recommended format for commit messages 4. Release guidelines - Is a "snapshots directory really the best way to do this? Why not use git tags instead? With regard to document creation, I'm new to the W3C process so maybe there are tools being used that I'm not familiar with. However, after reviewing a few other W3C repos, it seems like every doc is in raw html with a gross amount of repeated boilerplate all in one monolithic page. (This must be maddening when more than 2 people are working on a doc). Has any though been given to using a static site generator like HarpJS <http://harpjs.com/> or Jekyll <http://jekyllrb.com/>? Something where you can write in a more readable format like Markdown, use a page templates, and generate the HTML from that. It would also allow us to break up the monolithic page into sections, with each section as it's own file, and still have the output as one page. We could/should even include the output in the repo. On Tue, Apr 28, 2015 at 2:46 PM, Dave Jensen <david@jensen47.com> wrote: > If you want to look at changes to just one file, that is already supported > in git and github has a good interface for this. > > I suspect a git sub-repo would be overkill. Do we even need multiple > repos? Can you expand on other concerns of having just one repo? > > I've seen two good uses of sub-repos: > > 1. To include the source of a binary dependency. > > A good example is sass/node-sass which includes sass/libsass as a subrepo > for a specific commit. When node-sass is installed/built, it already has > the source for libsass from the subrepo, it builds is and continues > packaging itself for install. This usage doesn't seem appropriate for our > needs. > > 2. As a collection of other repos. > > I think I've seen this done for a color scheme for code editors. Each > subrepo was for a different code editor (vim, emacs, intellij, sublime, > textmate) and the "master" repo simply included each for convenience. The > only other file included was a README. If we need more than two repos for > projects, this *might *be a good use of subrepo. This also can be done > after the fact. > On Apr 28, 2015 8:50 AM, "Ted Guild" <ted@w3.org> wrote: > >> Re-adding the list in case others want to give input. >> >> I can make time Wednesday afternoon ET. >> >> Dave you probably surmised what we intend to do here but will elaborate >> as the minutes were scant and a plan wasn't fully formed. >> >> http://www.w3.org/2015/04/23-auto-minutes.html#item06 >> >> The two draft specs the Auto Working Group is chartered to bring through >> the standards process are presently in a repo that belonged to the >> Business Group. >> >> https://github.com/w3c/automotive-bg/ >> >> As both groups are going to co-exist, collaborate and/or transition work >> between them it would make sense in my opinion to have a single repo for >> both and to have clearly named sub-repositories (submodules) per project >> under. >> >> https://github.com/w3c/automotive >> >> The two specs being worked on should be in one folder since they >> >> https://github.com/w3c/automotive/vehicle_data_spec >> >> Significant deliverables for a project such as test cases for vehicle >> api can either be a sub-directory or sub-repos under vehicle_data_spec. >> We want to avoid having to handle huge merge requests across all >> projects but have convenience of being able to recursively update all of >> one's local checkouts. >> >> There are a few ways to go about this and to be honest I'm not sure of >> the pros and cons. I'll read up and ask advice of some who know git and >> better than I. >> >> https://github.com/git-commands/git-subrepo >> >> http://stackoverflow.com/questions/20137503/managing-a-git-with-sub-repositories >> >> On Mon, 2015-04-27 at 14:25 -0700, Dave Jensen wrote: >> > I'm free after 12:30pm PDT on Wednesday. >> > >> > On Mon, Apr 27, 2015 at 12:26 PM, Paul Boyes <pb@opencar.com> wrote: >> > Ted, >> > >> > >> > Let’s make this happen this week. How about touching base >> > Wednesday? >> > >> > Paul J. Boyes >> > -------------------------------- >> > Mobile: 206-276-9675 >> > Skype: pauljboyes >> > >> > >> > >> > >> > >> > >> > On Apr 27, 2015, at 1:16 AM, Kazuyuki Ashimura >> > <ashimura@w3.org> wrote: >> > >> > > Thanks, Dave! >> > > >> > > >> > > Kazuyuki >> > > >> > > On Sat, Apr 25, 2015 at 4:25 AM, Dave Jensen >> > > <david@jensen47.com> wrote: >> > > I'd be interested in helping out on this front as >> > > well. >> > > >> > > On Thu, Apr 23, 2015 at 3:33 AM, Automotive Working >> > > Group Issue Tracker <sysbot+tracker@w3.org> wrote: >> > > auto-ACTION-1: Work with ted and kaz on >> > > github repository layout >> > > >> > > http://www.w3.org/auto/wg/track/actions/1 >> > > >> > > Assigned to: Paul Boyes >> > > >> > > >> > > >> > > >> > > >> > > >> > > >> > > >> > > >> > > >> > > >> > > >> > > >> > > >> > >> > >> -- >> Ted Guild <ted@w3.org> >> W3C Systems Team >> http://www.w3.org >> >
Received on Tuesday, 28 April 2015 22:07:52 UTC