On Nov 10, 2010, at 3:58 AM, Renato Golin wrote:> On 10 November 2010 07:27, Chris Lattner <clattner at apple.com> wrote: >> I'd like to do more similar ones in the future, and encourage other contributors to also write other blog entries in general. > > Hi Chris, > > After discussing these topics in the dev meeting, I also have some input. > > First, blog posts are great for communicating changes and maybe > outlining design decisions, but these decisions change over time, and > the posts become obsolete.Right. Jan was specifically asking about the "why things were decided and what the tradeoffs were", which is an inherently a "moment in time" sort of thing. IMO, this is perfect for a blog post. Blog posts have the advantage that they are explicitly dated.> On the other hand, HTML documents, while > good for release process, are hard to change and keep it up-to-date.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.> As I said before, I'm looking for a (or writing a new) script to > convert from the Wiki to LLVM-HTML style, and I think we should use > the Wiki more often to keep not only the documents up-to-date, but > also the design decisions, libraries and how-tos.I personally really dislike the wiki. It is more difficult to keep up to date, isn't organized well, and has no inherent power over HTML. 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. I see the wiki as mainly useful for people collaboratively sketching out very early stuff. I personally never look at the wiki and have no idea if anything on there is up to date or useful. Looking now, I see a lot of stuff that should be folded into (for example) CodeGenerator.html after getting reviewed.>> I personally think that there are a several key aspects of our development process that contribute to ensuring that LLVM maintains its high quality over time: >> >> 1) peer review (review after commit is enough if people are willing to revert and if people actually do read the patches and speak up). > > This process can take months to apply and generally impact on the > productivity of the team that sent the patch in the first place. We > had a few cases where the patch was never looked upon until someone > hit the same problem and happened to find it in the llvm-commit list.If noone 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.>> 3) components that are not on-by-default can be held to lower standards while they are being implemented. If they work out and it seems like a good idea to turn them on by default, they should be given a really hard once-over. >> 4) continuous refactoring and improvement of the code base >> 5) being willing to throw away old stuff that no one is using or maintaining, or replace things that are broken and terrible. > > IMHO, these are the three key points that are maintaining the high > quality of LLVM and should be kept forever. As much as I disliked > having the union type removed, it was a good design decision. > > The same should go for back-ends. It's good to have a long list of > supported back-ends, but if they start hampering the evolution of the > rest, they should be turned off by default or even moved to a separate > patch/project outside the main distribution.Yes, I completely agree. The itanium and msil backends got axed not too long ago :)> In a nutshell, the design decisions should be communicated more > effectively, and a Wiki is a great place to start. Peer reviewers > should communicate via the Wiki, so patchers could learn and plan > before the next iteration and reduce the cost for everybody.I agree, I just don't think the wiki is the right forum for it :) -Chris
On Thu, Nov 11, 2010 at 1:46 AM, Chris Lattner <clattner at apple.com> wrote:> > On Nov 10, 2010, at 3:58 AM, Renato Golin wrote: > >> On 10 November 2010 07:27, Chris Lattner <clattner at apple.com> wrote: >>> I'd like to do more similar ones in the future, and encourage other contributors to also write other blog entries in general. >> >> Hi Chris, >> >> After discussing these topics in the dev meeting, I also have some input. >> >> First, blog posts are great for communicating changes and maybe >> outlining design decisions, but these decisions change over time, and >> the posts become obsolete. > > Right. Jan was specifically asking about the "why things were decided and what the tradeoffs were", which is an inherently a "moment in time" sort of thing. IMO, this is perfect for a blog post. Blog posts have the advantage that they are explicitly dated.I'm a big fan of putting such things *in the code* as comments. It does logically go with that bit of code, after all.
On 11 November 2010 12:42, Kenneth Uildriks <kennethuil at gmail.com> wrote:> I'm a big fan of putting such things *in the code* as comments. It > does logically go with that bit of code, after all.For some things, yes. But describing design decisions in comments gets either incomplete and scattered or too verbose and scattered. ;) I once had to do maintenance on a Python script that had 3x more comments than code. I never read them... -- cheers, --renato
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
> >>> I'd like to do more similar ones in the future, and encourage other >contributors to also write other blog entries in general.> >> > >> Hi Chris, > >> > >> After discussing these topics in the dev meeting, I also have some input. > >> > >> First, blog posts are great for communicating changes and maybe > >> outlining design decisions, but these decisions change over time, and > >> the posts become obsolete. > > > > Right. Jan was specifically asking about the "why things were decided and >what the tradeoffs were", which is an inherently a "moment in time" sort of >thing. IMO, this is perfect for a blog post. Blog posts have the advantage >that they are explicitly dated. > > I'm a big fan of putting such things *in the code* as comments. It > does logically go with that bit of code, after all.I agree that a blog is probably one of the better ways of documenting these things. A lot of discussions happen on the mailing lists and irc, and the person who is supposed to do the work (and probably initiated the discussions) could gather all the information and post it so that everyone can get the same information. With the proper tagging it is easy to find posts related to a specific module/library. Having a collective journal for the projects makes it possible to see if the code has diverged from the original design. It is useful to have a record of how people were thinking about the code and not only what they did to it. A blog post that is dated it is more likely to be treated with some skepticism if it very old, compared to Wiki and comments in code, which give the illusion they are up-to-date and accurate. That does not mean I am against comments in the code, but I like comments to explain more detailed things about the implementation. The only thing accurate is of course the code itself. We don't want to write blogs or comments unless it is needed, and finding a good balance is difficult. - Jan
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