You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@pdfbox.apache.org by Jukka Zitting <ju...@gmail.com> on 2009/09/29 12:30:27 UTC
Next PDFBox version and our backwards compatibility policy (Was:
Using Maven in PDFBox)
Hi,
2009/9/29 Andreas Lehmkühler <an...@lehmi.de>:
> Jukka Zitting schrieb:
>> PS. I set the build version to "1.0-SNAPSHOT" on the premise that we
>> may want to go for a 1.0 release once we're graduated from the
>> Incubator. Alternatively we could use "0.8.1-SNAPSHOT" to stick with a
>> more rigid major.minor.patch version numbering.
> IMHO there are two situations to go for a new major version:
>
> 1) the project reaches a defined status of being somehow complete
>
> 2) there are significant changes in the project
>
> I don't like the idea of 1). We neither have a concrete schedule nor a definition of
> a complete status e.g. like full support for documents following the pdf-specs 1.7
>
> If it comes to 2) IMHO there aren't any significant changes to go for a new major
> version except graduation. But I wouldn't have a problem with a change.
We already broke any backwards compatibility promises for the 0.x
series by releasing 0.8.0 with the renamed org.apache packages, and
I'd like to move to 1.x so we can take up a more strict backwards
compatibility policy.
Here's what I'd like us to adopt as policy for a major.minor.patch
versioning strategy:
* A major version upgrade can introduce major changes that can break
existing clients written against the APIs in previous releases.
* A minor version upgrade can introduce new features and APIs not
available in previous releases.
* A patch version upgrade can only fix errors in already existing
features. No new APIs will be introduced.
The goal of such a policy would be to achieve binary drop-in
compatibility for any upgrades from x.y.z to x.y'.z' where y' >= y.
To achieve this without unnecessarily restricting the implementation
flexibility we'd need to define what our public APIs are. The default
definition of all public and protected members of all public classes
and interfaces is pretty big.
BR,
Jukka Zitting
RE: Next PDFBox version and our backwards compatibility policy
(Was: Using Maven in PDFBox)
Posted by "Martinez, Mel" <m....@ll.mit.edu>.
Jukka Zitting [mailto:jukka.zitting@gmail.com]
> We already broke any backwards compatibility promises for the 0.x
> series by releasing 0.8.0 with the renamed org.apache packages, and
> I'd like to move to 1.x so we can take up a more strict backwards
> compatibility policy.
>
> Here's what I'd like us to adopt as policy for a major.minor.patch
> versioning strategy:
>
> * A major version upgrade can introduce major changes that can break
> existing clients written against the APIs in previous releases.
>
> * A minor version upgrade can introduce new features and APIs not
> available in previous releases.
>
> * A patch version upgrade can only fix errors in already existing
> features. No new APIs will be introduced.
>
> The goal of such a policy would be to achieve binary drop-in
> compatibility for any upgrades from x.y.z to x.y'.z' where y' >= y.
>
> To achieve this without unnecessarily restricting the implementation
> flexibility we'd need to define what our public APIs are. The default
> definition of all public and protected members of all public classes
> and interfaces is pretty big.
I totally concur with this. This is the versioning model that most of the industry seems to be moving to. I would slightly refine the 'minor' definition to say that 'minor' upgrades can introduce additional API, but should not break existing API.
Re: Next PDFBox version and our backwards compatibility policy (Was:
Using Maven in PDFBox)
Posted by Daniel Wilson <wi...@gmail.com>.
I like your definition of major/minor/patch versions.
>>The default definition of all public and protected members of all public
classes and interfaces is pretty big.
It is big. But any lesser definition is incomplete, IMO.
Daniel
On Tue, Sep 29, 2009 at 6:30 AM, Jukka Zitting <ju...@gmail.com>wrote:
> Hi,
>
> 2009/9/29 Andreas Lehmkühler <an...@lehmi.de>:
> > Jukka Zitting schrieb:
> >> PS. I set the build version to "1.0-SNAPSHOT" on the premise that we
> >> may want to go for a 1.0 release once we're graduated from the
> >> Incubator. Alternatively we could use "0.8.1-SNAPSHOT" to stick with a
> >> more rigid major.minor.patch version numbering.
> > IMHO there are two situations to go for a new major version:
> >
> > 1) the project reaches a defined status of being somehow complete
> >
> > 2) there are significant changes in the project
> >
> > I don't like the idea of 1). We neither have a concrete schedule nor a
> definition of
> > a complete status e.g. like full support for documents following the
> pdf-specs 1.7
> >
> > If it comes to 2) IMHO there aren't any significant changes to go for a
> new major
> > version except graduation. But I wouldn't have a problem with a change.
>
> We already broke any backwards compatibility promises for the 0.x
> series by releasing 0.8.0 with the renamed org.apache packages, and
> I'd like to move to 1.x so we can take up a more strict backwards
> compatibility policy.
>
> Here's what I'd like us to adopt as policy for a major.minor.patch
> versioning strategy:
>
> * A major version upgrade can introduce major changes that can break
> existing clients written against the APIs in previous releases.
>
> * A minor version upgrade can introduce new features and APIs not
> available in previous releases.
>
> * A patch version upgrade can only fix errors in already existing
> features. No new APIs will be introduced.
>
> The goal of such a policy would be to achieve binary drop-in
> compatibility for any upgrades from x.y.z to x.y'.z' where y' >= y.
>
> To achieve this without unnecessarily restricting the implementation
> flexibility we'd need to define what our public APIs are. The default
> definition of all public and protected members of all public classes
> and interfaces is pretty big.
>
> BR,
>
> Jukka Zitting
>
Re: Next PDFBox version and our backwards compatibility policy (Was:
Using Maven in PDFBox)
Posted by Andreas Lehmkühler <an...@lehmi.de>.
Hi,
Daniel Wilson schrieb:
>>> If the library doesn't allow access to these objects
> it'll be a significant blow to the capabilities of PDFBox.
>
> Certainly. Is restricting access (e.g. changing public objects/methods to
> private/protected) even what's being proposed?
>
> That would be one of the simplest ways to break a lot of client
> applications.
No, I don't think so. But if we talk about public APIs, we have to
define them. That doesn't lead to the converse argument, that
everything, which isn't part of a public API has to be protected.
There are a lot of users just using these public APIs and we have to
ensure that they don't have to change there code with every minor
version of pdfbox. Those who dig down to the deep of pdfbox have to
check on every new version if there are any relevant changes.
If there are things people do by digging down into the deep, which are
interesting for others, then we should implement that feature somewhere
at a more public place, see e.g [1] or [2]
BR
Andreas Lehmkühler
[1] https://issues.apache.org/jira/browse/PDFBOX-532
[2] https://issues.apache.org/jira/browse/PDFBOX-505
Re: Next PDFBox version and our backwards compatibility policy (Was:
Using Maven in PDFBox)
Posted by Daniel Wilson <wi...@gmail.com>.
>> If the library doesn't allow access to these objects
it'll be a significant blow to the capabilities of PDFBox.
Certainly. Is restricting access (e.g. changing public objects/methods to
private/protected) even what's being proposed?
That would be one of the simplest ways to break a lot of client
applications.
Daniel
On Wed, Sep 30, 2009 at 12:19 PM, <Ad...@swmc.com> wrote:
> I have to dig down into the COSObjects in order to do things like get the
> "indirect reference to a page object" for some of my work with bookmarks.
> Here's an example (item is a PDOutlineItem):
>
> COSObject targetPageRef =
>
> (COSObject)((COSArray)item.getAction().getCOSDictionary().getDictionaryObject("D")).get(0);
>
> Although I'd like a cleaner way of doing this, I feel there will still
> always be cases where people will need to dig down into the technical
> details like this. If the library doesn't allow access to these objects
> it'll be a significant blow to the capabilities of PDFBox.
>
> --Adam
>
>
>
>
> Andreas Lehmkühler <an...@lehmi.de>
> 09/29/2009 22:33
> Please respond to
> pdfbox-dev@incubator.apache.org
>
>
> To
> pdfbox-dev@incubator.apache.org
> cc
>
> Subject
> Re: Next PDFBox version and our backwards compatibility policy (Was: Using
> Maven in PDFBox)
>
>
>
>
>
>
> Hi,
>
>
> Jukka Zitting schrieb:
> > Hi,
> >
> > 2009/9/29 Andreas Lehmkühler <an...@lehmi.de>:
> >> Jukka Zitting schrieb:
> >>> PS. I set the build version to "1.0-SNAPSHOT" on the premise that we
> >>> may want to go for a 1.0 release once we're graduated from the
> >>> Incubator. Alternatively we could use "0.8.1-SNAPSHOT" to stick with a
> >>> more rigid major.minor.patch version numbering.
> >> IMHO there are two situations to go for a new major version:
> >>
> >> 1) the project reaches a defined status of being somehow complete
> >>
> >> 2) there are significant changes in the project
> >>
> >> I don't like the idea of 1). We neither have a concrete schedule nor a
> definition of
> >> a complete status e.g. like full support for documents following the
> pdf-specs 1.7
> >>
> >> If it comes to 2) IMHO there aren't any significant changes to go for a
> new major
> >> version except graduation. But I wouldn't have a problem with a change.
> >
> > We already broke any backwards compatibility promises for the 0.x
> > series by releasing 0.8.0 with the renamed org.apache packages, and
> > I'd like to move to 1.x so we can take up a more strict backwards
> > compatibility policy.
> >
> > Here's what I'd like us to adopt as policy for a major.minor.patch
> > versioning strategy:
> >
> > * A major version upgrade can introduce major changes that can break
> > existing clients written against the APIs in previous releases.
> >
> > * A minor version upgrade can introduce new features and APIs not
> > available in previous releases.
> >
> > * A patch version upgrade can only fix errors in already existing
> > features. No new APIs will be introduced.
> >
> > The goal of such a policy would be to achieve binary drop-in
> > compatibility for any upgrades from x.y.z to x.y'.z' where y' >= y.
> >
> I missed that point of view. You're absolutely right, we need that policy.
>
> > To achieve this without unnecessarily restricting the implementation
> > flexibility we'd need to define what our public APIs are. The default
> > definition of all public and protected members of all public classes
> > and interfaces is pretty big.
> Perhaps we should start looking at the provided examples and try to
> define what case is a typical pdfbox-process and what is needed for
> those cases, e.g.
>
> in general: PDDocument, PDPage, ...
> Textectracting: PDFTextStripper, PDFToHTML
> PDFToImage: PDFImageWriter
>
> BR
> Andreas Lehmkühler
>
>
>
>
>
>
>
> ? Click here to submit conditions
>
> This email and any content within or attached hereto from Sun West
> Mortgage Company, Inc. is confidential and/or legally privileged. The
> information is intended only for the use of the individual or entity named
> on this email. If you are not the intended recipient, you are hereby
> notified that any disclosure, copying, distribution or the taking of any
> action in reliance on the contents of this email information is strictly
> prohibited, and that the documents should be returned to this office
> immediately by email. Receipt by anyone other than the intended recipient is
> not a waiver of any privilege. Please do not include your social security
> number, account number, or any other personal or financial information in
> the content of the email. Should you have any questions, please call (800)
> 453 7884.
Re: Next PDFBox version and our backwards compatibility policy (Was: Using
Maven in PDFBox)
Posted by Ad...@swmc.com.
I have to dig down into the COSObjects in order to do things like get the
"indirect reference to a page object" for some of my work with bookmarks.
Here's an example (item is a PDOutlineItem):
COSObject targetPageRef =
(COSObject)((COSArray)item.getAction().getCOSDictionary().getDictionaryObject("D")).get(0);
Although I'd like a cleaner way of doing this, I feel there will still
always be cases where people will need to dig down into the technical
details like this. If the library doesn't allow access to these objects
it'll be a significant blow to the capabilities of PDFBox.
--Adam
Andreas Lehmkühler <an...@lehmi.de>
09/29/2009 22:33
Please respond to
pdfbox-dev@incubator.apache.org
To
pdfbox-dev@incubator.apache.org
cc
Subject
Re: Next PDFBox version and our backwards compatibility policy (Was: Using
Maven in PDFBox)
Hi,
Jukka Zitting schrieb:
> Hi,
>
> 2009/9/29 Andreas Lehmkühler <an...@lehmi.de>:
>> Jukka Zitting schrieb:
>>> PS. I set the build version to "1.0-SNAPSHOT" on the premise that we
>>> may want to go for a 1.0 release once we're graduated from the
>>> Incubator. Alternatively we could use "0.8.1-SNAPSHOT" to stick with a
>>> more rigid major.minor.patch version numbering.
>> IMHO there are two situations to go for a new major version:
>>
>> 1) the project reaches a defined status of being somehow complete
>>
>> 2) there are significant changes in the project
>>
>> I don't like the idea of 1). We neither have a concrete schedule nor a
definition of
>> a complete status e.g. like full support for documents following the
pdf-specs 1.7
>>
>> If it comes to 2) IMHO there aren't any significant changes to go for a
new major
>> version except graduation. But I wouldn't have a problem with a change.
>
> We already broke any backwards compatibility promises for the 0.x
> series by releasing 0.8.0 with the renamed org.apache packages, and
> I'd like to move to 1.x so we can take up a more strict backwards
> compatibility policy.
>
> Here's what I'd like us to adopt as policy for a major.minor.patch
> versioning strategy:
>
> * A major version upgrade can introduce major changes that can break
> existing clients written against the APIs in previous releases.
>
> * A minor version upgrade can introduce new features and APIs not
> available in previous releases.
>
> * A patch version upgrade can only fix errors in already existing
> features. No new APIs will be introduced.
>
> The goal of such a policy would be to achieve binary drop-in
> compatibility for any upgrades from x.y.z to x.y'.z' where y' >= y.
>
I missed that point of view. You're absolutely right, we need that policy.
> To achieve this without unnecessarily restricting the implementation
> flexibility we'd need to define what our public APIs are. The default
> definition of all public and protected members of all public classes
> and interfaces is pretty big.
Perhaps we should start looking at the provided examples and try to
define what case is a typical pdfbox-process and what is needed for
those cases, e.g.
in general: PDDocument, PDPage, ...
Textectracting: PDFTextStripper, PDFToHTML
PDFToImage: PDFImageWriter
BR
Andreas Lehmkühler
? Click here to submit conditions
This email and any content within or attached hereto from Sun West Mortgage Company, Inc. is confidential and/or legally privileged. The information is intended only for the use of the individual or entity named on this email. If you are not the intended recipient, you are hereby notified that any disclosure, copying, distribution or the taking of any action in reliance on the contents of this email information is strictly prohibited, and that the documents should be returned to this office immediately by email. Receipt by anyone other than the intended recipient is not a waiver of any privilege. Please do not include your social security number, account number, or any other personal or financial information in the content of the email. Should you have any questions, please call (800) 453 7884.
Re: Next PDFBox version and our backwards compatibility policy (Was:
Using Maven in PDFBox)
Posted by Andreas Lehmkühler <an...@lehmi.de>.
Hi,
Jukka Zitting schrieb:
> Hi,
>
> 2009/9/29 Andreas Lehmkühler <an...@lehmi.de>:
>> Jukka Zitting schrieb:
>>> PS. I set the build version to "1.0-SNAPSHOT" on the premise that we
>>> may want to go for a 1.0 release once we're graduated from the
>>> Incubator. Alternatively we could use "0.8.1-SNAPSHOT" to stick with a
>>> more rigid major.minor.patch version numbering.
>> IMHO there are two situations to go for a new major version:
>>
>> 1) the project reaches a defined status of being somehow complete
>>
>> 2) there are significant changes in the project
>>
>> I don't like the idea of 1). We neither have a concrete schedule nor a definition of
>> a complete status e.g. like full support for documents following the pdf-specs 1.7
>>
>> If it comes to 2) IMHO there aren't any significant changes to go for a new major
>> version except graduation. But I wouldn't have a problem with a change.
>
> We already broke any backwards compatibility promises for the 0.x
> series by releasing 0.8.0 with the renamed org.apache packages, and
> I'd like to move to 1.x so we can take up a more strict backwards
> compatibility policy.
>
> Here's what I'd like us to adopt as policy for a major.minor.patch
> versioning strategy:
>
> * A major version upgrade can introduce major changes that can break
> existing clients written against the APIs in previous releases.
>
> * A minor version upgrade can introduce new features and APIs not
> available in previous releases.
>
> * A patch version upgrade can only fix errors in already existing
> features. No new APIs will be introduced.
>
> The goal of such a policy would be to achieve binary drop-in
> compatibility for any upgrades from x.y.z to x.y'.z' where y' >= y.
>
I missed that point of view. You're absolutely right, we need that policy.
> To achieve this without unnecessarily restricting the implementation
> flexibility we'd need to define what our public APIs are. The default
> definition of all public and protected members of all public classes
> and interfaces is pretty big.
Perhaps we should start looking at the provided examples and try to
define what case is a typical pdfbox-process and what is needed for
those cases, e.g.
in general: PDDocument, PDPage, ...
Textectracting: PDFTextStripper, PDFToHTML
PDFToImage: PDFImageWriter
BR
Andreas Lehmkühler