[LLVMdev] LLVM maintainers, code reviews

[Chris Lattner]

On Nov 11, 2010, at 5:08 AM, Renato Golin wrote:
> On 11 November 2010 07:46, Chris Lattner <clattner at apple.com> wrote:
>> It's actually not any harder to change and keep up to date than anything else.  HTML pages have the advantage of showing up in a recursive grep of the sourcebase, and showing up in llvm-commits so they fall into the peer review process.
> 
> Hi Chris,
> 
> I understand that this is more of a personal preference than a
> technical discussion...
> 
> Diff-ing HTML is not easy and enforcing style even less. Most Wiki
> have revision control (albeit, different than your main svn repo),
> good diffing and collaboration tools.
> 
> It's true that both HTML and Wiki tend to become out-dated if no one
> maintains it and a blog post is outdated by definition, but explicitly
> done so (dated).
> 
> I agree that blog posts are good to convey decisions made, but would
> be good to have it immortalized somewhere (HTML or Wiki).

It's true that this is partially about personal preference, but it goes beyond that.  The wiki doesn't fit into the social infrastructure we have for the project: changes to it aren't reviewed on a -commits list, people without commit access can modify it, etc.  Depending on your perspective, this is a good thing or bad thing.  One datapoint is that UIUC refuses to host wiki.llvm.org specifically because they have policies against hosting web sites with no control over the content.

Beyond the social aspects, the wiki doesn't fit into our release infrastructure either.  llvm/docs is snapshotted with each release and archived.  This helps with changing APIs and other stuff, which means that you can read about LLVM 1.0's alias analysis stuff at http://llvm.org/releases/1.0/docs/AliasAnalysis.html if you really want to :)  Because the wiki is not in SVN, it can't realistically do this.

>> If you're liking the Wiki because you don't have commit access to the LLVM repo (making it harder to update the docs there) then we should grant you commit access.
> 
> That's not the point. The story goes like this...
> 
> Me, Devang and Talin were discussing the document I've written about
> debug information. Both sent me lots of corrections, typos,
> suggestions, in the body of the email, which I had to change the HTML
> doc and re-send them. Every iteration they would find things, suggest
> others, until Talin said: we should put this in the Wiki!
> 
> While this is pretty much what you said (draft writing on wiki), there
> are lots of things that will remain draft quality for a long time,
> like how to produce debug information.

As I mentioned, I don't have a problem with using the wiki as a collaborative development tool, so long as useful docs migrate back to the official html docs.

> So, as you said, people should write drafts in Wiki and more finalized
> documents in HTML (a I concur), Wikis are good to start documents, and
> HTML are good to immortalize them. So, encouraging people to start
> docs in the wiki and having a way to convert them to HTML (I found
> some Python scripts in Google code) would be a good thing.
> 
> Later additions, when the HTML doc is already stable, could be
> manageable via SVN diff.

Right.  My next objection is that the wiki isn't being used just for collaborative development.  For example, the "common backend tasks", "faq", "using llvm" and other stuff should be merged into the official docs.  I'm fine keeping wishlist and external project lists on the wiki.

-Chris