[Twisted-Python] incompatible change - need revert before release

[Glyph Lefkowitz]

> On Nov 20, 2015, at 1:42 AM, Adi Roiban <adi at roiban.ro> wrote:
> 
> 
> On 20 November 2015 at 10:32, Glyph Lefkowitz <glyph at twistedmatrix.com <mailto:glyph at twistedmatrix.com>> wrote:
> > On Nov 20, 2015, at 12:08 AM, Adi Roiban <adi at roiban.ro <mailto:adi at roiban.ro>> wrote:
> >
> > It was released before 15.4
> >
> > Twisted Web 15.2.0 (2015-05-18)
> > ===============================
> >
> > Features
> > --------
> >  - twisted.web.server.Site accepts requestFactory as constructor
> >    argument. (#7016)
> >
> > ----------
> >
> > Not sure if rollback is the right thing to do... but I have no idea how to proceed as any change will back the compatibility.
> >
> > I guess that we should just create a normal bug ticket and fix this issue
> 
> Thanks for finding the changelog entry; sorry for the false alarm.
> 
> If it's been in a release, then there's probably nothing to do.  It's a shame that this went out, but once a breakage like this has happened we have to live with it because otherwise, as you say, we'd be breaking compatibility for the people that already upgraded.  For those that need to support both versions, keyword arguments are the way to go.
> 
> Well, in public interfaces we could just stop mixing *args and **kwargs with other arguments. 
> 
> It is more work for maintainers, but as a library user I find it much easier to see the exact args in the docs, rather than seeing  *args  / **kwargs and then navigating the inheritance path to find out all supported arguments.

I'm not quite sure what you're referring to in this case; but generally, I agree.  If you pass a parameter, you should document it with @param even if your arg list says *args / **kwargs.  This is how I tried to document, for example, optionsForClientTLS.

-glyph

-------------- next part --------------
An HTML attachment was scrubbed...
URL: </pipermail/twisted-python/attachments/20151120/859953b9/attachment-0002.html>