Re: [pyrus] generate-pear2

On Thu, Jul 8, 2010 at 9:32 AM, till <till@php.net> wrote: > OK, cc'd pear-dev cause I bet others will find this interesting as > well. Or maybe I'll just look like a fool (ohai, Internetz). > > On Thu, Jul 8, 2010 at 4:13 PM, Brett Bieber <brett.bieber@gmail.com> wrote: >> On Wed, Jul 7, 2010 at 5:29 PM, till <till@php.net> wrote: >>> Hey again! =) >>> >>> I find a lot of what is created by "generate-pear2" there very confusing. >> >> It's all documented here: >> http://pear.php.net/manual/en/pyrus.commands.make.php >> http://pear.php.net/manual/en/pyrus.commands.package.php >> >>> For starters - we don't need the trunk, branches, tags dir. A lot of >>> people use a dvcs such as git. >> >> Agreed. >> >>> Then, there's these files and directories: >>> API-0.1.0 >>> RELEASE-0.1.0 >>> package_compatible.xml >>> packagexmlsetup.php >>> stub.php >>> README >>> extrasetup.php >>> customcommand >>> customroles >>> customtasks >>> >>> ... while it's cool that pyrus can do a lot. It's not very helpful for >>> people getting into PEAR. I've recently showed this to two people who >>> have never done a PEAR package before and they didn't feel like >>> exploring all of that if they didn't have to. For a first timer, it's >>> time consuming though to figure out what is needed. >> >> Hmm... so, do you think we should remove the empty dirs and un-needed >> files? Perhaps add an option to create a full package skeleton or just >> a barebones (heh) skeleton? > > Yeah, something light: > > generate-pear2 > generate-pear2-(full/light) > > Whatever you want. > >>> Particularly, I don't understand what API* and RELEASE* are for when I >>> have package.xml. And what I have to do with package_compatible.xml, >>> packagexmlsetup.php and extrasetup.php. I'm also thinking that the >>> stub.php file shouldn't be generated at all and should be instead >>> created when I do generate-phar. >> >> The package.xml is not an ideal place to maintain the API and RELEASE >> notes, unless you understand the package xml schema. Writing XML that >> validates to the package-2.0.xsd is a much higher learning curve than >> "Put your release notes into a file named RELASE-X.X.X, and api >> release notes into a file API-X.X.X before you run pyrus make" > > Ok, so basically I don't need to touch my package.xml ever again once > I created it (and until of course I'm adding/removing files)? Correct! > That's interesting and good to know. > > Is the developer expected to always create those files for each > release and will they have to stay around to show the history? Yep, create a new one. Once you have the new files, you can remove the old ones because previous release notes are inside the package.xml files, but there's no harm keeping them around IMO. >> For the rest, read the docs: >> packagexmlsetup.php >> >> http://pear.php.net/manual/en/pyrus.commands.make.php#pyrus.commands.make.packagexmlsetupÝä7ò?\)¿Xÿ_„o- >> Ê >> >> extrasetup.php >> >> http://pear.php.net/manual/en/pyrus.commands.package.php#pyrus.commands.package.extrasetup >> >> stub.php >> >> http://pear.php.net/manual/en/pyrus.commands.package.php#pyrus.commands.package.stub >> >> Perhaps adding links inside those files to the documentation would help? > > Yeah, wouldn't hurt. :-) > > Thanks for digging those up. > >>> All in all, it looks like this is indeed the whole deal of what's >>> possible with pyrus, but for the sake of avoiding a learning wall, I >>> think it should be trimmed heavily to not make people deal with all >>> this if they don't have to. It probably wouldn't hurt to have >>> documentation on the bits and pieces when people tackled package.xml >>> and are ready to get deeper into it. >>> >>> I also looked up generate-pear2 in the manual, it didn't really >>> explain much or any of it. >> >> That's because I documented it instead of Greg, IIRC. :-) >> http://pear.php.net/manual/en/pyrus.commands.generatepear2.phpwÅ >> ùØÈätohåVú] >> >> Feel free to help expand it. > > It's like the first thing when I google "generate-pear2", so I guess > linking from that page to the above links (you shared) is all that's > needed. Good suggestion. >>> Last but not least - src/PEAR2/PackageName/Main.php? Maybe I missed >>> parts of the discussion, but why is that created instead of >>> src/PEAR2/PackageName.php? >> >> Aha, GREAT question. This allows individual packages to be used in >> svn:externals, and I'd encourage package developers to follow this >> model. > > Interesting. But I think bending the layout to make svn:externals > happy sounds weird to me. svn:externals as well as git submodules. > Most packages right now are $foo = new Cat_Bar();, with this, it'll > change to $foo = new Cat_Bar_Main(); - if that is wanted. Shouldn't it > be enforced and not just suggested? (Not that I want that. ;-)) $foo = new PEAR2\Cat\Bar\Main(); with namespaces. I'd prefer it be a recommendation, but I wouldn't be against it being added to the pear2 standards. This would mean class Main would be reserved, and every PHP PEAR2 package would be expected to have class Main as well as interface Exception (in packages that throw exceptions) for the absolute minimum. -- Brett Bieber