Wow, your mail is too long to get into details because we may end bikeshedding, but I'd like to point a couple of things. Replying in line.
On 03/12/13 14:54, Jorge Cardoso Leitão wrote: > [...] > 1. Unless there are people using pyglet, there aren't people > contributing to pyglet, which means that the effort per person with > project complexity increases. > 2. Unless there are good standards on how to contribute, the project > complexity increases too fast with project size to be bearable in long run. > > I'll give you one example of what I'm referring: in this commit > <https://code.google.com/p/pyglet/source/detail?r=88a2e9928d5b>, I > didn't contributed because there is still no clear instructions of what > I should do to contribute. I agree with you that the docs are important, but I don't think it's that difficult to contribute to pyglet. In fact I've tried to not let new patches unattended for too long to keep newcomers interested (you're one of them, btw!). I started to work on the tickets in July and before that the issue tracker was kind of abandoned. That's bad and makes pyglet status look worse than it is. Still lot of work to be done on that front. > Furthermore, a patch was added to the trunk without API documentation: > the public API of batch changed, and that was not documented (I'm not > blaming anyone; it is what it is). > What I mean with "API not documented" is that this function is now part > of pyglet's API: if anyone wants to re-order groups within a Batch, > he can now use that functionality. Thus, in the Programming Guide (what > I call "API docs"), this must be included *as part of the code.* I don't agree or (perhaps) I'm not sure if I understand you because IMHO `it is` documented. Pyglet has two main documentation areas: - the programming guide - docs extracted from the code (API docs) When the problems generating the documentation are sorted out, that new method that exposes an internal feature of the Batch class will be documented. > My suggestion is that we don't commit to the trunk (and close the issue) > unless the full package is complete: > code+testing+references+API docs. This makes adding new functionalities > much more time consuming, but makes Pyglet's complexity to grow much > slower with project size than the current grow. It's a good idea, until you check how pyglet tests work :) I still think we call API docs a different thing, but I see your point. > [...] > - Finally, don't rush. If you are not sure it is ready, it is because it > is not. If we release 1.2 without proper documented API, Pyglet loses > credibility > and makes it more difficult to attract more users and contributors. I'd be happy if we could get things moving. If you think they already are, then... success! :) Look, pyglet 1.2 is perfectly usable for me. It was before I started contributing, and after putting some hours into the projects... it's a little bit better. As I said, any help is welcome. I'd like to get the doc generation working, write the missing bits when needed and keep working on the bug tracker until it shines. At some point I expect most pyglet users will be using 1.2 -- when we are happy with it we can release a beta. As Alex told me: do whatever tickles your fancy (not textual words, but I like the idea). Kind regards, Juan -- You received this message because you are subscribed to the Google Groups "pyglet-users" group. To unsubscribe from this group and stop receiving emails from it, send an email to [email protected]. To post to this group, send email to [email protected]. Visit this group at http://groups.google.com/group/pyglet-users. For more options, visit https://groups.google.com/groups/opt_out.
