[LLVMdev] LLVM maintainers, code reviews

[Renato Golin]

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


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

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.


> If no one responds after a week, please ping the patch.  One major issue with a distributed group of reviewers is that everyone assumes that someone else will look at it.  Pinging helps with this.

Ok, will do.


--
cheers,
--renato