Hi all It seems to me that Juan has too much work in hands. I think it is of upmost importance to improve the documentation on *API documentation* and *how to contribute*:
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. 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.* 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. - Regarding the missing code, I think the approach here is to define priorities: what is release blocker? what is important? what is minor? These decisions have to come from experience contributors that know the project as a whole and can make these judge calls. It is the whole point of ticket triaging. If in doubt, discuss in the mailing list. If the issue is not ready to be solved because it is too difficult, let it be there. In my perspective, is far better to have an open issue with a patch waiting to be documented than a code full of patches with out-of-sync documentation. The reason is that while it is a patch within a ticket, it has a very clear context (to address the ticket). When it is in the code, the context it belongs has to be fully documented, both on a lower level (References) and higher level (API docs). - Regarding the obscure code, it is hard, especially if we don't have people with skills to tackle it. The viable (and valuable) option in some circumstances is to consider dropping support. This again is a way of decreasing the project complexity, in this case by removing components that cannot be fixed, lack documentation or the effort to maintain is higher than the value they provide to the project. - 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. In the end, this boils down to make Pyglet community friendly so it can attract people to help: more *API documentation* means more users; more documentation on *how to contribute* means more users wanting to contribute, which means less work for us all, specially for Juan (or, at least, he can spend his time on matters that require senior contributors). I can help on any of those. Regards, Jorge On Sunday, December 1, 2013 11:02:27 AM UTC+1, Juan J. Martínez wrote: > > Hello, > > It's been long time since my last report! > > I started working on pyglet about 5 months ago and although some > progress has been made (we're below the 130 issues mark, wow!), there's > a lot of work to do. > > I'm happy with the idea of more people using hg tip (the repo code) as > it is where the fixes go and we're getting rid of the most > frequent/annoying issues in 1.2 alpha1. > > Now that I've been working with the source code for some time I'm not as > optimistic as I was 5 months ago regarding future releases :) but I'm > still here with you! > > The main reasons for my despair are: > > - Documentation: the doc generation is kind of broken, docs re: > migrating from pyglet 1.1.x are missing, the programming guide is not > 100% in sync with 1.2 -- this is BAD > > - Missing code: there are some TODOs in the code, some of them are out > of reach for me and my current skills (I can read and apply patches from > contributors though) > > - Obscure bugs: there are some bugs related to platform code (ie. audio > drivers problems in win, linux or mac) that I can't investigate or even > reproduce > > We can improve the situation and, even pyglet 1.2 is not perfect (yet), > I still think it's the way forward and eventually we will get there. > > I don't know when we will be ready for a new release, but I have to > tackle the doc issues before we can think of getting anywhere close to a > beta release. > > Any help will be appreciated! > > Regards, > > Juan > > -- > jjm's home: http://www.usebox.net/jjm/ > blackshell: http://blackshell.usebox.net/ > -- 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.
