Hey hey, I wasn't going to say anything but since this is dragging on...
On Sat, Dec 5, 2009 at 1:08 AM, Doug Cutting <cutt...@apache.org> wrote: > Would we permit someone to mirror other files from trunk on the website? Yes, definitely. Most projects publish their websites by pushing files into SVN. Many projects automate this - commit an xml file, its turned into html and published online. That is in fact the encouraged process, though we do allow other mechanisms (like a plugin which takes confluence content and pushes that out automatically). > What's special about documentation? Less legal risk, less risk that anyone puts a bug in docs that crashes a users computer or corrupts their data or takes down the internet, generally not subject to patent concern, less desire for the general public to fork and redistribute, and much more. Like, barriers to working on it have to be as low as possible or no-one will do it, people inclined to work on docs are often less technical, etc etc. Perhaps it helps to flip the question around: what is special about (source) code? And the answer is: lots :) > its changes are subject to vetos, etc. Not on most of the projects I work on! Most projects use lazy consensus for documentation. I don't think I have *ever* seen someone veto a documentation patch. <snip/> > It's otherwise treated just like code. Well, in some ways (that you pointed out) docs are treated a lot like code, and in many other ways they aren't. >> Publication & release are two different things - thats the point. > > I don't see that yet. Can you tell me more about the difference? I use > "publish", "distribute" and "release" more or less synonymously when > referring to project content. I'd say we don't really have precise definitions that will provide you with a model explaining exactly what is and isn't ok in the general case, and I think it won't help to look for it either. Instead, judgement should be applied to the specific case. > Subversion contains only working drafts. And stable branches and release tags and documentation and websites and quickbooks and contact info and meeting minutes and ... We use subversion for nearly everything that needs to be auditable and be backed up and be collaboratively edited. We don't always particularly care about the versioning bit :) But, for the sake of illustration, let's do a mental exercise. The ASF does creation and distribution of software to the general public. When we say "software" we mostly mean "source code (and some binaries for convenience)". Pretty much everything around here is structured to support this creation and distribution of software. There's a variety of supporting things, like websites, incubators, an org structure, various committees, conferences, etc. All of it supports creation and distribution of our software. What constitutes the software that a project releases to the public depends on that project. Subversion is one project, it has a website and it creates software which it distributes. Subversion releases a single tarball of (mostly C) source code with some build scripts and whatnot. Running the build produces an apache module, a server program, a client program and some utilities. Subversion's users then install this software on their system and use it. Most subversion users probably get a pre-built binary from a third party. The subversion project provides a manual for how to install and use svn on its website, but I suspect most users will actually use the svn book. There is a relatively small side activity for subversion which involves using its libraries and APIs to build custom client software that interacts with a subversion server (or perhaps even extend the server though I think very few people do that). For this activity, you need the API docs we're talking about here. Of course, the subversion developers themselves need those API docs too. It's a fair assumption that the expert developer people using these API docs know *quite a lot* about subversion already, including about its versioning and compatibility policies, how to download releases and code out of svn, etc etc. It's also a fair assumption that the most important API to develop against is in fact the SVN trunk API. So, subversion publishes their trunk API docs nightly, for the convenience of their own developers and the surrounding tool developer community. All those people mostly want trunk API docs, and they want them mostly so they don't have to run doxygen themselves. There's really no need to protect the normal users of the subversion website from "bad" API docs, they won't be using those docs at all. Now, the point of this long story: subversion as a community has thought about all this and are evidently doing a pretty good job at keeping users and wider developer community (well perhaps not the java dev community who are afraid of native code :-D ) happy. Within all this context, one of the subversion developers (or this I assume) asked a tech-focused question on where they should put their API docs and how to do so automatically. Good that he asked, ideally he should receive a quick answer that allows him to get on with creating software and distributing it to the public - incubator is here to enable that. The best response in this case is probably to look for a similar project around the ASF that has already figured out a similar process and see if things are compatible. Like, httpd or apr. Ah, they do the same. Cool, done. Perhaps the worst possible response is making an assertion about policy saying in effect "you're not allowed to do what you're trying to do", followed by a long discussion thread about why that assertion is correct, based on an interpretation of generic ASF policy as it applies or (c|sh)ould apply to websites. Please don't make these generic/sweeping assertions when someone from an incubating project asks a specific-to-them specific question. The effect is to stall progress which is unhealthy for that project's community. If you have an idea about what the policy is, check your idea against the extensive docs on www.apache.org/dev/ and incubator.apache.org. If your idea is in there, point people at the documented policy. If the reverse of what you thought is in there, you can answer with what you just learned. If the answer is not in there, then maybe it makes sense to start a discussion thread (where I sort-of expect people that talk about policy volunteer to update the website docs with the outcome of the discussion), but don't bother the incubating project with that stuff, and in the meantime its a good idea to err on the side of let-them-get-on-with-it. If you must make a generic assertion that's not obviously backed by existing policy documentation, make sure to add "I think that the normal approach is" or "I believe that the best thing to do is" rather than state SHOULD or MUST. Focus on helping the incubating project achieve their goal. If you make such a generic assertion anyway, and several of your peers around here goes "excuse me, I disagree", then the reflex behavior should be something like "oh, go ahead then". There can still be a discussion about what the policy should be, but _please_ _please_ just let the incubating project go and get stuff done, start a new thread. Always remember the incubator is not here to invent policy and apply it to incubating projects. The incubator is here to help incubating projects navigate the ASF so they can create and distribute software "ASF style". You know, often times I think the best engineers can be the worst policy-makers: as engineers we tend to build models and abstractions and look for the rules and the invariants and then express those as clearly as possible. But abstractions are leaky, invariants are variable, and clear rules can look pretty aggressive to the casual human. We have to let go of all that rigid thinking in order to make a reasonable policy that can be used by humans. I always look to creative commons for great examples of this. I.e. compare http://creativecommons.org/licenses/GPL/2.0/ to http://www.gnu.org/licenses/old-licenses/gpl-2.0.html I think nearly everyone can agree on which is "friendlier" :) cheers! Leo --------------------------------------------------------------------- To unsubscribe, e-mail: general-unsubscr...@incubator.apache.org For additional commands, e-mail: general-h...@incubator.apache.org
