Post without Account — your post will be reviewed, and if appropriate, posted under Anonymous. You can also use this link to report any problems registering or logging in.

Best platform for this fork?

  • 11 Replies
  • 2725 Views
*

Offline Phil

  • Global Moderator
  • Sr. Member
  • *****
  • 412
    • View Profile
Best platform for this fork?
« March 03, 2017, 03:51:44 PM »
I have contacted as many people as I could locate, who have either recently submitted bug reports to CPAN (RT system), or have their own CPAN packages that prereq PDF::API2. I have heard back from several of them, and most ask at least one of the following questions:

Why did you make a fork? Isn't PDF::API2 alive and well?

As I explained in the introduction to PDF::API2 in the Free Software section of my site, I have not dreamed of supporting my own version of PDF::API2 since I was a little boy. I started playing with it about 3 or 4 years ago, and quickly discovered a lot of shortcomings and other bugs and issues. Plus, the documentation needed a lot of polishing. So, I started submitting changes to the official maintainer, Steve Simms. Some small ones were accepted and became part of the product. However, I ended up with a massive rewrite of Content.pm, to fix a number of small bugs, add some enhancements, fix the documentation, and very importantly, rearrange the presentation order in a more logical manner. I sent it off to Steve, and waited. And waited. And waited. After nearly a year (I got sidetracked on some other work-related stuff), I finally wrote to Steve and asked when my work might appear in a release. His reply: it was too much for him to deal with, so he threw it away.

As it was apparent that we were at loggerheads when it came to what would go into the official version, and my work would never appear, I came to the realization that if other people ever were to see my work, I would have to release it myself. A fork, in other words. I wasn't happy at the prospect, but that was the only way my contributions would see the light of day. I considered three alternatives for the release process:

  • patch files to be applied against specific official releases. I wasn't too happy with this one, as it requires tools that not everyone has, to apply a patch, and any patch could be invalidated at the next official release, requiring a new patch. Many of the "patch" files would be huge.
  • replacement files for updated files, rather than patches or the entire product. I would be responsible for incorporating the latest official changes into my copies. Unchanged files would not be distributed (use the official distribution). As with the patches, users would still be on the hook for manually updating their libraries.
  • full release, as .tar.gz and .zip files. This would be the full PDF::API2 release (my updated files plus the rest of the unchanged official release files). The user would simply unpack the files and overwrite their PDF::API2 directory. I felt that this would be the least confusing to users, as they don't have to maintain/upgrade the official version, and then apply updates (patches or full files) to their library.
All of these choices have advantages and disadvantages. I wish that Steve would be more receptive to including my work, so there would simply be the official PDF::API2 v2.xxx release and that's that. As long as he isn't, I need some way of releasing the code. Now, I'm not entirely locked into the full release option. It would be possible for me to also release patches and/or updated files, but there would be multiple versions of each, as the underlying official release changes. The Changes-CTS file lists updated files for each release. Does anyone want to express a strong preference for one of these alternative methods?

Please note that in these comments, I'm not trying to diss Steve Simms. He's done a lot of quality work on reviving PDF::API2 and working on reported bugs, and I respect that. It's just that I feel his scope of interest is just too narrow — basically no major changes, no POD improvements, and no enhancements to speak of.

Why don't you put it on GitHub and/or CPAN?

This could still happen. I stated that I wanted to initially handle this myself, via my site and forum, to gauge the reaction and see if enough people were interested in working with my release to make it worthwhile putting it in those repositories. A number of people have suggested that this creates a chicken-and-egg problem: if it's not conformable to most developers' workflows (on GitHub), or it's not directly installable from CPAN, most people won't want to bother with it. I understand the point. Would more people be interested in testing my work, discussing problems and directions, and submitting bug fixes and enhancements; if it were on GitHub? That sounds like something that I could handle, and being public, it costs nothing. I just need to find a good cookbook for doing this sort of thing on GitHub. As people work with me and show they're competent and willing to row in the same direction, I could open it up to their directly submitting (checking in) code (pull requests, etc., as I understand GitHub). I would still want the final say, especially if I feel it's taking the product in an undesirable direction, but in general I would welcome updates that I don't have to check over and merge into the code myself. It would be good to have some trusted lieutenants. And if they're happy because it's on GitHub and works with their workflows, so much the better. I would probably still keep my current distribution, unless I also have the code on CPAN.

Maybe Steve would allow my code as a GitHub branch of the official product? This would satisfy the call for it to be on GitHub. However, we're not talking minor patches here and there, but really major revisions. Eventually, almost every file could be hit — do they all need to be initially branched so they have the same branch label? I'm not terribly familiar with the ins and outs of Git, and so would need some hand-holding on this.

I also got suggestions to put this on CPAN. This would be the finished product (release version), not intermediate work-in-progress snapshots as with GitHub, so this would co-exist alongside the GitHub repository. The problem I see with putting my version on CPAN is that what do I call it? There is already a PDF::API2 (maintained by Steve Simms). The official CPAN distribution would still exclusively be his. My understanding is that I would still have to distribute my branch (as an installable .tar.gz or .zip file) on my site. For a CPAN-installable package, my understanding is that I'd have to call it something else. PDF::API3 seems to be a stillborn fork of PDF::API2 (from before when Steve took over). I had a suggestion that I apply to take it over, but I'm reluctant at this point to toss out Otto's work (I haven't looked at it in detail, but I don't think it's a straight copy). PDF::API4 and above are available. The problem is, the world knows this Perl PDF interface package as PDF::API2, not as PDF::API (version 2). I could well put out an API3 or API4, but there would be no other packages using it for a while. Maybe in time, some existing packages might convert over to my version, but I would not expect a mass flight from PDF::API2 to PDF::API4. Again, a chicken-and-egg problem if it's not called PDF::API2.

Does anyone have suggestions for how my version could be put on CPAN and immediately attract a vibrant community? Short of Steve having a change of heart, and accepting my code changes into version 2.xxx, I'm not sure how that would happen.

How would you like to see it done?

I'm open to suggestions on better ways to present my version than what I have now (custom site code for the finished release repository and .tar.gz/.zip/other full packages, and a standard forum for discussions and bug reports). I'd be just as happy to use some other bug-tracking software such as RT on CPAN, or GitHub's bug/discussion software, or something that plugs into my site. A number of people would like something that integrates smoothly with their workflows, and GitHub seems to be commonly recommended. I could continue to use this forum for general discussions that don't correspond to specific bugs. What do all of you think?
« Last Edit: April 10, 2017, 05:23:40 PM by Phil »

*

Offline Phil

  • Global Moderator
  • Sr. Member
  • *****
  • 412
    • View Profile
Re: Best platform for this fork?
« Reply #1: March 04, 2017, 02:00:20 PM »
One thing I want to emphasize, is that currently this fork is a direct drop-in replacement for the official PDF::API2 release. That's why I did not change the name to PDF::API4 (or whatever). Granted, there are some additional steps after you install the official PDF::API2 release, to unpack the archive file (.tar.gz or .zip) either directly over your PDF::API2 library, or to a working directory and then copy it over.

Marco Pessotto, keeper of several PDF::API2-using packages, had an interesting suggestion: that I rename the module (to avoid conflict with the official release), and create a PDF::API::Any package to use one or the other (my fork or the official) package that is installed. I understand that this would require rewriting code to use PDF::API::Any; instead of use PDF::API2; (unless I misunderstand him), and I have been trying to avoid changing existing packages and private work. However, it would permit distribution on CPAN, bringing my work (and others who contribute) to a wider audience. Is anyone familiar with such an arrangement? Of course, I could always bite the bullet, rename mine to PDF::API4, and hope to attract enough users to make it worthwhile (new and existing packages using PDF::API4 instead of PDF::API2). That's why I didn't put it on CPAN (or GitHub) immediately — I wanted to test the waters first, but what I'm hearing is that without CPAN, it's still not of interest.

There would still be the risk of name collisions between the official version and my fork, such as my creating a PDF::API2::NewStuff and Steve's later creating a different-function module of the same name. If I want to maintain strict compatibility (so my fork remains a drop-in replacement), I would either have to rewrite NewStuff to be a functional superset of his version, or (less palatably) rename my version. This would be a problem whether or not my project is renamed, as I still want it to be as drop-in as possible.

In spite of my efforts to maintain compatibility, the act of cleaning up the module structure, and making sure that class inheritance is properly done, may yet result in not-quite compatibility. I'm just trying to avoid breaking existing uses of PDF::API2, even if mine is renamed to API4 (still a minor incompatibility).

Another thought: perhaps my version here could be seen by Steve as an alpha (or beta) test for major changes, that he could siphon off into the official version once they're "proven out" here. That way, the two versions would stay a lot closer, with this fork really being a sandbox or testbed for new development.
« Last Edit: March 04, 2017, 02:07:03 PM by Phil »

*

Offline sciurius

  • Jr. Member
  • **
  • 67
    • View Profile
    • Website
Re: Best platform for this fork?
« Reply #2: March 04, 2017, 02:19:08 PM »
As long as your PDF::API2 is a drop-in replacement for Steve's, it doesn't matter much.
Fixes? Great. But as soon as you start adding features that Steve's PDF::API2 doesn't have applications that are going to use these features must be coded to explicitly use yours. The only way I see this happen is by using a different name. And then it is less relevant if it's called PDF::API4 or PDF::API::Tng. Applications need to use the exact name.

*

Offline Phil

  • Global Moderator
  • Sr. Member
  • *****
  • 412
    • View Profile
Re: Best platform for this fork?
« Reply #3: March 07, 2017, 04:15:17 PM »
Well, I have been adding (minor) new features, and so in a minor sense I have already broken compatibility with PDF::API2's official release. Offline, lots of people have urged me to rename it to PDF::API4 and put the development on GitHub and the finished releases on CPAN. That way, new work can be fit into developers' workflow (GitHub) and the wide world can instantly download and install finished releases (CPAN).  Unfortunately, no one has promised that they will use API4 or take more than a cursory look at it, so it's still possible that this will end up wasted effort.

My chief reservation at this point is that no one's code will immediately use a PDF::API4 — they will have to rewrite (or initially write) their code to use API4 instead of the familiar API2. This may limit the public uptake versus having a drop-in replacement for API2. My hope is still that all my work would be incorporated into the API2, but I must proceed with this work rather than waiting for something to happen on that front. One thing I might consider doing is taking useful external packages (e.g., Lite) and modifying them to use API4, and shipping them with API4. Are there any licensing restrictions I should be aware of?

There is also the issue of whether I should wait until I have cleaned up the class structure (if needed) before releasing an API4. I don't want to clean it up after the first release, and then introduce minor incompatibilities in a later API4 release. I think it would be safer to move the class structure work to a front burner, and get that squared away (with any needed API changes) before going to the first API4 release. I'm trying to maintain as much compatibility as I can with the official PDF::API2 release (Steve's), but at some point they're bound to diverge. I like Marco's idea of being able to switch between releases, although that still requires a change to existing code.

I see that some time around early 2015 that Otto Hirr put a read-only copy of PDF::API3 v3.001 on GitHub (the external dates are "2 years ago", while internal dates still match April 2009 of the CPAN release). Since PDF::API2 is at 2.xxx, I wonder if I should continue the pattern and make mine v4.xxx? Also, it may be something overlooked by Otto, but there are many POD examples using PDF::API (not PDF::API[2/3]). At this point, I don't know how much code improvement was done on API3, or whether it is still just a snapshot of API2 v0.72. I will have to diff the files at some point and see what Otto did, and whether any of that code should be glommed for API4.

Finally, both GitHub and CPAN offer bug tracking (ticket) systems. Frankly, I'm not terribly fond of the interface to either of them (especially CPAN's RT, which seems to require emailing posts). The SMF forum I'm using here offers much better markup than GitHub's use of Markdown, but does not auto-number new bug reports (I might be able to add that to SMF). If I had to use one of the two, it would probably be GitHub's. I would keep a discussion area on this forum for general discussions that do not relate to a particular bug, and move all the bugs over to GitHub. Is there a way to add "feature requests" and possibly "rejected bugs" to GitHub's open (unresolved) and closed (resolved) categories?

If anyone has pointers to good "cookbook" tutorials for the best way to implement these things, I'd appreciate hearing about them.
« Last Edit: March 07, 2017, 11:06:20 PM by Phil »

*

Offline sciurius

  • Jr. Member
  • **
  • 67
    • View Profile
    • Website
Re: Best platform for this fork?
« Reply #4: March 08, 2017, 03:02:56 PM »
Let's assume for the time being that Api4 (short for Phil's incarnation of PDF::API2) is upward compatible with Api2 (short for Steve's PDF::API2).

As long as I do not depend on new features or critical bug fixes, I don't care which one I use.

As soon as I start using a single new feature, I must use Api4 and I must be sure that that is the one I'm using. The requirement
Code: [Select]
use PDF::API2 3.000; is not sufficient, since Steve may one day bump his version to 3.000 and beyond. Besides, CPAN won't let you add a PDF::API2 module unless you become (co-)owner of the PDF::API2 namespace. So you must use a different module name.

As soon as I start using a new feature, I am writing new code and changing Api2 to Api4 doesn't sound like a big challenge to me.

*

Offline Phil

  • Global Moderator
  • Sr. Member
  • *****
  • 412
    • View Profile
Re: Best platform for this fork?
« Reply #5: May 02, 2017, 01:03:38 PM »
I've noticed that Steve seems to have disappeared, and the CPAN installation (2.031) hasn't been touched in over 3 months. Nor have any bug reports been answered. Does anyone know if PDF::API2 is still being maintained, or if Steve is looking for someone to take it over? I haven't been able to contact him, but I'm willing to offer to take over ownership of PDF::API2 if he wants to bail. Considering how different our approaches are, I don't think we can share ownership. Maybe he would like to scale back his involvement and just fix bugs once in a while?

If I don't take over PDF::API2, the alternative is to start up PDF::API4 on GitHub and CPAN. I could use some advice on the best way to manage this, from someone who has been there. My platform is Windows7 (I don't currently have a Linux system). The GitHub side doesn't look too complicated, at least from the introductory videos. Is there a simple publish directly from GitHub to CPAN, or does it involve a lot of work? Would there be any point in putting my 3.001 through 3.003 versions online (as 4.001 through 4.003) and the next release is 4.004, or should I just start with my current state as 4.001? Are there standard tools for updating the module VERSION numbers, or is that something where I need to roll my own? Finally, I prefer the GitHub ticket system to CPAN's, using tags for Feature Request and Rejected Bug (and possibly other states), but I would probably keep general discussions on this forum.

*

Offline sciurius

  • Jr. Member
  • **
  • 67
    • View Profile
    • Website
Re: Best platform for this fork?
« Reply #6: May 03, 2017, 04:46:17 AM »
Three months is far from exceptional. Modules are considered orphaned after several years.

As for the GitHub: If you can run git you can use GitHub. It's trivial. I can lend a hand if you want.

For publishing to CPAN: perl Makefile.PL; make all test dist; and upload the resultant dist to CPAN. I use the script "cpan-upload-http" (available on CPAN) to make it real easy.

*

Offline Phil

  • Global Moderator
  • Sr. Member
  • *****
  • 412
    • View Profile
Re: Best platform for this fork?
« Reply #7: May 03, 2017, 09:01:58 AM »
OK, I'll try again with Steve. If he wants to bail out and turn PDF::API2 over to me, that would be a lot cleaner than starting up a competing PDF::API4.

I've just started looking at GitHub and viewing some tutorials. It looks like the basics are doable, but I may need to tap your knowledge about some of the more advanced stuff, including the ticketing system.

I was hoping for a direct GitHub-to-CPAN publishing link, but it sounds like there isn't one. I have to build a "dist" on my PC and upload to CPAN? Is cpan-upload-http some sort of FTP wrapper? Can I just use FileZilla and do a single upload, or does CPAN have some oddball rules?

*

Offline sciurius

  • Jr. Member
  • **
  • 67
    • View Profile
    • Website
Re: Best platform for this fork?
« Reply #8: May 04, 2017, 07:53:07 AM »
To upload you need the proper .tar.gz, and this is produced by executing "perl Makefile.PL; make all; make test; make dist". Although you can skip the "make test" better be safe then sorry.

The 'normal' way to upload is to visit the cpan page, login in with your user name and password, select the upload function, and point it to the .tar.gz. A tool like cpan-upload-http does this for you. It's just  lot easier.

*

Offline Phil

  • Global Moderator
  • Sr. Member
  • *****
  • 412
    • View Profile
Re: Best platform for this fork?
« Reply #9: May 09, 2017, 11:38:17 AM »
I heard back from Steve Simms. His explanation for the long absence is
Quote
I tend to work in chunks -- fairly long absences followed by a burst of activity and a release.  Three months isn't particularly unusual.
I don't think that's particular good for the health of a product, as it leaves questions and bug fixes hanging for an awfully long time. Maybe it would be OK for a more mature product with few bugs, but API2 has a fairly hefty bug list.

Anyway, I asked him if he planned to keep maintaining PDF::API2, and he said he has no intention of handing it over to anyone else. He doesn't care if someone forks it. He did request that I call it something else (other than PDF::APIn) because he considers my work a fork, rather than a version succession. That's not totally unreasonable (considering the questions he's gotten about PDF::API3), but I'd like to get some feedback before I put this out on GitHub and CPAN under some new name. If not API4, any suggestions? There are already PDFlib and PDF::Utils out there. I'd like a name that gives a good idea at a glance what it's about, especially as people are going to be inclined to look for PDF::APIn rather than a completely new name. I think it should probably be under PDF::, but beyond that, I need to think about it. It's more oriented towards creating a new PDF than editing an existing one, but it can be used for limited changes to an existing document.

PDF::Base, PDF::Builder, PDF::BildR, PDF::Make, PDF::Maker, PDF::MakR, PDF::Creator, PDF::Gen

*

Offline sciurius

  • Jr. Member
  • **
  • 67
    • View Profile
    • Website
Re: Best platform for this fork?
« Reply #10: May 09, 2017, 04:58:36 PM »
Good. I'd go for PDF::Builder or PDF::Creator. I see no added benefits for weird abbreviations like Bldr MakR and so on.

Remember: Ken Thompson was once asked what he would do differently if he were redesigning the UNIX system. His reply: "I'd spell creat with an e."

*

Offline Phil

  • Global Moderator
  • Sr. Member
  • *****
  • 412
    • View Profile
Re: Best platform for this fork?
« Reply #11: July 14, 2017, 02:54:52 PM »
1) now named PDF::Builder

2) source on GitHub at PhilterPaper/Perl-PDF-Builder

3) distributable module and documentation on CPAN at PMPERRY/PDF::Builder

4) bug reports (open/closed, with "enhancement", "duplicate", etc. tags) under GitHub "Issues". Please avoid using the CPAN RT system, as there is no guarantee it will be closely watched.

5) general discussions (not related to a specific bug or feature request) will continue here (www.catskilltech.com/forum/) for the time being. Eventually they may be moved to the GitHub wiki.
« Last Edit: July 23, 2017, 08:27:49 AM by Phil »