Details

    • Type: Bug Bug
    • Status: Closed
    • Priority: Minor Minor
    • Resolution: Fixed
    • Affects Version/s: 10.9.1.0
    • Fix Version/s: 10.10.1.1
    • Component/s: Documentation
    • Labels:
      None

      Description

      In the Developer's Guide we describe two kinds of upgrade, "full" and "soft". I think we used to use the terms "hard" and "soft", and "hard" was changed to "full" to provide a more accurate description of what happens. There are still a few leftover occurrences of "hard" in the docs here and there.

      However, "soft" doesn't provide much indication of what happens in that kind of upgrade. Would "partial" be more correct? If not, is there a good alternative?

      I can go through the docs and fix the language based on whatever you all think makes sense.

      1. derby-6061-chinese.diff
        2 kB
        Dag H. Wanvik
      2. DERBY-6061-2.zip
        7 kB
        Kim Haase
      3. DERBY-6061-3.diff
        7 kB
        Kim Haase
      4. DERBY-6061-code2.stat
        0.2 kB
        Kim Haase
      5. DERBY-6061-code2.diff
        3 kB
        Kim Haase
      6. DERBY-6061-2.diff
        7 kB
        Kim Haase
      7. DERBY-6061.zip
        7 kB
        Kim Haase
      8. DERBY-6061.stat
        0.2 kB
        Kim Haase
      9. cdevcsecureroles.html
        15 kB
        Kim Haase
      10. DERBY-6061-code.diff
        0.7 kB
        Kim Haase
      11. DERBY-6061.diff
        0.7 kB
        Kim Haase

        Activity

        Hide
        Rick Hillegas added a comment -

        Thanks for logging this issue, Kim. I agree that the terms "hard" and "soft" aren't very meaningful. However, I don't think that the terms "full" and "partial" are much better. I think that the defining behavior of the two types of upgrades can be summarized as follows:

        o Hard - In this kind of upgrade, on-disk data in the database is changed. This kind of upgrade is NOT reversible. That is, once you hard-upgrade the database, then you can no longer run older versions of the Derby engine jar file against the database. By "older", I mean a version with a lower major.minor identifier. In addition, hard upgrade typically enables new features.

        o Soft - In this kind of upgrade, on-disk data in the database is NOT changed. If your application misbehaves after this upgrade, you can reverse the upgrade by running your old version of the Derby engine jar. Typically, soft upgrade does not enable new features.

        So we need a pair of terms which capture these distinctions. Maybe "feature" vs. "bugfix".

        Thanks,
        -Rick

        Show
        Rick Hillegas added a comment - Thanks for logging this issue, Kim. I agree that the terms "hard" and "soft" aren't very meaningful. However, I don't think that the terms "full" and "partial" are much better. I think that the defining behavior of the two types of upgrades can be summarized as follows: o Hard - In this kind of upgrade, on-disk data in the database is changed. This kind of upgrade is NOT reversible. That is, once you hard-upgrade the database, then you can no longer run older versions of the Derby engine jar file against the database. By "older", I mean a version with a lower major.minor identifier. In addition, hard upgrade typically enables new features. o Soft - In this kind of upgrade, on-disk data in the database is NOT changed. If your application misbehaves after this upgrade, you can reverse the upgrade by running your old version of the Derby engine jar. Typically, soft upgrade does not enable new features. So we need a pair of terms which capture these distinctions. Maybe "feature" vs. "bugfix". Thanks, -Rick
        Hide
        Rick Hillegas added a comment -

        Another approach to the problem might be to eliminate all mention of soft upgrade. The user can't request or disable soft upgrade. It happens automatically. Maybe we should just talk about upgrade. It's the hard, irreversible, data-changing behavior when you specify "upgrade=true" after installing the jar files of a release whose major.minor id is greater than your old release. Thanks.

        Show
        Rick Hillegas added a comment - Another approach to the problem might be to eliminate all mention of soft upgrade. The user can't request or disable soft upgrade. It happens automatically. Maybe we should just talk about upgrade. It's the hard, irreversible, data-changing behavior when you specify "upgrade=true" after installing the jar files of a release whose major.minor id is greater than your old release. Thanks.
        Hide
        Dag H. Wanvik added a comment -

        > Another approach to the problem might be to eliminate all mention of soft upgrade

        This may be good for most users' perspectives. Devs need two terms to cover the "soft" behavior as well, and dev terms easily slip into end user docs.
        Bu also users need sometimes be aware that a new version of the database jar could cause issues even without upgrade=true, and also sometimes new features/fixes are available without hard upgrade, so it would be good to have an easy way to characterize that situation.

        What about code (or jar) upgrade vs. database upgrade ?

        Show
        Dag H. Wanvik added a comment - > Another approach to the problem might be to eliminate all mention of soft upgrade This may be good for most users' perspectives. Devs need two terms to cover the "soft" behavior as well, and dev terms easily slip into end user docs. Bu also users need sometimes be aware that a new version of the database jar could cause issues even without upgrade=true, and also sometimes new features/fixes are available without hard upgrade, so it would be good to have an easy way to characterize that situation. What about code (or jar) upgrade vs. database upgrade ?
        Hide
        Kim Haase added a comment -

        I'm afraid I'm getting cold feet on this. We've been making the full upgrade/soft upgrade distinction since 10.2. References to soft upgrade seem to be limited to the Developer's Guide and Reference Manual upgrade topics; references to full upgrade are scattered here and there. I think it might confuse people more if we change the terminology than if we don't. It's probably more important to be consistent in our language than to try to find exactly correct terminology.

        We should get rid of references to "hard upgrade". I find only two references to hard upgrade in the docs. There's one sentence in http://db.apache.org/derby/docs/10.9/devguide/cdevcsecureroles.html, which at this point should probably be removed entirely:

        "Old databases must be (hard) upgraded to at least Release 10.5 before roles can be used."

        There's also an error message in the error message list:

        08004 – User '<authorizationID>' cannot hard upgrade database '<databaseName>'. Only the database owner can perform this operation.

        It would probably be simple enough to remove "hard" from this message.

        Show
        Kim Haase added a comment - I'm afraid I'm getting cold feet on this. We've been making the full upgrade/soft upgrade distinction since 10.2. References to soft upgrade seem to be limited to the Developer's Guide and Reference Manual upgrade topics; references to full upgrade are scattered here and there. I think it might confuse people more if we change the terminology than if we don't. It's probably more important to be consistent in our language than to try to find exactly correct terminology. We should get rid of references to "hard upgrade". I find only two references to hard upgrade in the docs. There's one sentence in http://db.apache.org/derby/docs/10.9/devguide/cdevcsecureroles.html , which at this point should probably be removed entirely: "Old databases must be (hard) upgraded to at least Release 10.5 before roles can be used." There's also an error message in the error message list: 08004 – User '<authorizationID>' cannot hard upgrade database '<databaseName>'. Only the database owner can perform this operation. It would probably be simple enough to remove "hard" from this message.
        Hide
        Kim Haase added a comment -

        Here are two minimal patches that remove references to hard upgrade.

        DERBY-6061.diff removes a sentence from the "Using SQL roles" topic (cdevcsecureroles.html):

        M src/devguide/cdevcsecureroles.dita

        DERBY-6061-code.diff removes the word "hard" from one of the messages in the code:

        M java/engine/org/apache/derby/loc/messages.xml

        This may be all that is needed.

        Show
        Kim Haase added a comment - Here are two minimal patches that remove references to hard upgrade. DERBY-6061 .diff removes a sentence from the "Using SQL roles" topic (cdevcsecureroles.html): M src/devguide/cdevcsecureroles.dita DERBY-6061 -code.diff removes the word "hard" from one of the messages in the code: M java/engine/org/apache/derby/loc/messages.xml This may be all that is needed.
        Hide
        Mike Matrigali added a comment -

        i am wondering why you would remove the sentence about roles, the point of soft upgrade is that it is possible that users of the current release
        software may still have databases that are at a version level prior to 10.5.

        Show
        Mike Matrigali added a comment - i am wondering why you would remove the sentence about roles, the point of soft upgrade is that it is possible that users of the current release software may still have databases that are at a version level prior to 10.5.
        Hide
        Dag H. Wanvik added a comment -

        I'm OK with keeping soft upgrade vs. (full) upgrade. In general, I think keeping hints in the docs that the database needs to be at a certain release before a feature is available is helpful, cf. Java's Javadocs which state from what SE release a new class or methods exists.
        So I agree with Mike here; let the sentence on roles stand but with the harmonized language.

        Show
        Dag H. Wanvik added a comment - I'm OK with keeping soft upgrade vs. (full) upgrade. In general, I think keeping hints in the docs that the database needs to be at a certain release before a feature is available is helpful, cf. Java's Javadocs which state from what SE release a new class or methods exists. So I agree with Mike here; let the sentence on roles stand but with the harmonized language.
        Hide
        Knut Anders Hatlen added a comment -

        The code patch probably also needs to update ErrorCodeTest, which checks the exact message text of this error.

        Show
        Knut Anders Hatlen added a comment - The code patch probably also needs to update ErrorCodeTest, which checks the exact message text of this error.
        Hide
        Kim Haase added a comment -

        Thanks for all the great advice. I will revise the Dev Guide topic and add to the code patch. While I am at it, I notice there is one other reference to hard upgrade in messages that I can find.

        java/engine/org/apache/derby/loc/messages_it.properties:08004.C.6=L''utente ''

        {0}'' non pu\u00F2 eseguire l''aggiornamento hard del database ''{1}''. Solo il proprietario del database pu\u00F2 eseguire questa operazione.

        Interestingly, the other European-language properties files that contain this message don't seem to have the problem:

        java/engine/org/apache/derby/loc/messages_de_DE.properties:08004.C.6=Benutzer ''{0}

        '' kann kein Upgrade der Datenbank ''

        {1}'' erzwingen. Hierzu ist nur der Datenbankeigent\u00FCmer berechtigt.
        java/engine/org/apache/derby/loc/messages_es.properties:08004.C.6=El usuario ''{0}'' no puede realizar una actualizaci\u00F3n completa de la base de datos ''{1}

        ''. S\u00F3lo el propietario de la base de datos puede realizar esta operaci\u00F3n.
        java/engine/org/apache/derby/loc/messages_fr.properties:08004.C.6=L''utilisateur ''

        {0}

        '' ne peut pas effectuer une mise \u00E0 niveau mat\u00E9rielle de la base de donn\u00E9es ''

        {1}

        ''. Seul le propri\u00E9taire de la base de donn\u00E9es peut effectuer cette op\u00E9ration.

        German and French just use plain "upgrade"; Spanish uses "full upgrade" (how clever). I'm helpless with the Asian ones, though.

        New patches will be coming.

        Show
        Kim Haase added a comment - Thanks for all the great advice. I will revise the Dev Guide topic and add to the code patch. While I am at it, I notice there is one other reference to hard upgrade in messages that I can find. java/engine/org/apache/derby/loc/messages_it.properties:08004.C.6=L''utente '' {0}'' non pu\u00F2 eseguire l''aggiornamento hard del database ''{1}''. Solo il proprietario del database pu\u00F2 eseguire questa operazione. Interestingly, the other European-language properties files that contain this message don't seem to have the problem: java/engine/org/apache/derby/loc/messages_de_DE.properties:08004.C.6=Benutzer ''{0} '' kann kein Upgrade der Datenbank '' {1}'' erzwingen. Hierzu ist nur der Datenbankeigent\u00FCmer berechtigt. java/engine/org/apache/derby/loc/messages_es.properties:08004.C.6=El usuario ''{0}'' no puede realizar una actualizaci\u00F3n completa de la base de datos ''{1} ''. S\u00F3lo el propietario de la base de datos puede realizar esta operaci\u00F3n. java/engine/org/apache/derby/loc/messages_fr.properties:08004.C.6=L''utilisateur '' {0} '' ne peut pas effectuer une mise \u00E0 niveau mat\u00E9rielle de la base de donn\u00E9es '' {1} ''. Seul le propri\u00E9taire de la base de donn\u00E9es peut effectuer cette op\u00E9ration. German and French just use plain "upgrade"; Spanish uses "full upgrade" (how clever). I'm helpless with the Asian ones, though. New patches will be coming.
        Hide
        Kim Haase added a comment -

        Here's another thought: the Dev Guide topic "Soft upgrade limitations" is superfluous.

        At releases 10.1 and 10.2 this topic described specific features of those releases that were not available in a soft upgrade. Then for releases 10.3 through 10.5 this topic was not modified, so the features list was obsolete. Then we took out the feature-specific text and pointed readers to the release notes. Now almost all the information in that topic is also in the previous topic ("Upgrading a database"), with the exception of a couple of sentences that could be moved there.

        I am going to revise the patch to make these changes – what do you think?

        Show
        Kim Haase added a comment - Here's another thought: the Dev Guide topic "Soft upgrade limitations" is superfluous. At releases 10.1 and 10.2 this topic described specific features of those releases that were not available in a soft upgrade. Then for releases 10.3 through 10.5 this topic was not modified, so the features list was obsolete. Then we took out the feature-specific text and pointed readers to the release notes. Now almost all the information in that topic is also in the previous topic ("Upgrading a database"), with the exception of a couple of sentences that could be moved there. I am going to revise the patch to make these changes – what do you think?
        Hide
        Kim Haase added a comment -

        Attaching DERBY-6061-2.diff, DERBY-6061.stat, and DERBY-6061.zip, with the following Developer's Guide changes:

        D src/devguide/tdevupgradesoft.dita
        M src/devguide/cdevcsecureroles.dita
        M src/devguide/tdevupgradedb.dita
        M src/devguide/derbydev.ditamap

        Also attaching DERBY-6061-code2.diff and DERBY-6061-code2.stat, with the following code changes:

        M java/engine/org/apache/derby/loc/messages.xml
        M java/engine/org/apache/derby/loc/messages_it.properties
        M java/testing/org/apache/derbyTesting/functionTests/tests/lang/ErrorCodeTest.java

        I hope these help make the upgrade documentation and terminology more clear and consistent.

        Show
        Kim Haase added a comment - Attaching DERBY-6061 -2.diff, DERBY-6061 .stat, and DERBY-6061 .zip, with the following Developer's Guide changes: D src/devguide/tdevupgradesoft.dita M src/devguide/cdevcsecureroles.dita M src/devguide/tdevupgradedb.dita M src/devguide/derbydev.ditamap Also attaching DERBY-6061 -code2.diff and DERBY-6061 -code2.stat, with the following code changes: M java/engine/org/apache/derby/loc/messages.xml M java/engine/org/apache/derby/loc/messages_it.properties M java/testing/org/apache/derbyTesting/functionTests/tests/lang/ErrorCodeTest.java I hope these help make the upgrade documentation and terminology more clear and consistent.
        Hide
        Dag H. Wanvik added a comment -

        Thanks, Kim. Looks good. The sentence reintroduced for roles should probably say "fully upgraded" now: Since we retain the term soft upgrade, the term "upgrade" is not precise. Maybe we should state in the section "upgrading a database" that any usage of the unqualified term "upgrade" will (normally, unless with the soft qualifier) mean a full upgrade? Or did you do through other uses to check that they are properly qualified?

        Show
        Dag H. Wanvik added a comment - Thanks, Kim. Looks good. The sentence reintroduced for roles should probably say "fully upgraded" now: Since we retain the term soft upgrade, the term "upgrade" is not precise. Maybe we should state in the section "upgrading a database" that any usage of the unqualified term "upgrade" will (normally, unless with the soft qualifier) mean a full upgrade? Or did you do through other uses to check that they are properly qualified?
        Hide
        Kim Haase added a comment -

        Thanks, Dag, both those changes make sense. I did not check all uses of "upgrade" for the "full" qualification, but a spot check suggests that plain old "upgrade" is often used.

        Show
        Kim Haase added a comment - Thanks, Dag, both those changes make sense. I did not check all uses of "upgrade" for the "full " qualification, but a spot check suggests that plain old "upgrade" is often used.
        Hide
        Kim Haase added a comment -

        Attaching DERBY-6061-3.diff and DERBY-6061-2.zip (just to be confusing) with additional changes to cdevcsecureroles.dita and tdevupgradedb.dita. More feedback is welcome!

        Show
        Kim Haase added a comment - Attaching DERBY-6061 -3.diff and DERBY-6061 -2.zip (just to be confusing) with additional changes to cdevcsecureroles.dita and tdevupgradedb.dita. More feedback is welcome!
        Hide
        Kim Haase added a comment -

        Haven't heard any comments in a week, so –

        Committed patch DERBY-6061-3.diff to documentation trunk at revision 1445404.

        If there are any problems with this, please let me know. I plan to commit the code patch tomorrow and resolve the issue, but I can reopen it if necessary.

        Show
        Kim Haase added a comment - Haven't heard any comments in a week, so – Committed patch DERBY-6061 -3.diff to documentation trunk at revision 1445404. If there are any problems with this, please let me know. I plan to commit the code patch tomorrow and resolve the issue, but I can reopen it if necessary.
        Hide
        Dag H. Wanvik added a comment -

        For the simplified Chinese, you can remove this character ("hard"): 硬
        For traditional Chinese you can remove these two characters
        ("enforced"): 強制

        Netbeans let's you edit the properties files directly, but
        unfortunately, it changes all the hex encoding to another case
        In any case, we know now they do contain the "hard" adverb (to the
        extend the word category applies for Chinese..

        Thanks,
        Dag

        Show
        Dag H. Wanvik added a comment - For the simplified Chinese, you can remove this character ("hard"): 硬 For traditional Chinese you can remove these two characters ("enforced"): 強制 Netbeans let's you edit the properties files directly, but unfortunately, it changes all the hex encoding to another case In any case, we know now they do contain the "hard" adverb (to the extend the word category applies for Chinese.. Thanks, Dag
        Hide
        Kim Haase added a comment -

        Thanks, Dag. Unfortunately both my mailer and browser show the actual Chinese characters instead of the unicode versions (backslash-u followed by a 4-digit hex code), which are all I can see in the text editor. Could you please let me know the unicode equivalents?

        Show
        Kim Haase added a comment - Thanks, Dag. Unfortunately both my mailer and browser show the actual Chinese characters instead of the unicode versions (backslash-u followed by a 4-digit hex code), which are all I can see in the text editor. Could you please let me know the unicode equivalents?
        Hide
        Dag H. Wanvik added a comment -

        Hi Kim, uploading a diff with for the localization files. If you apply it, you should be able to see that the texts have changed by removing the characters I indicated.

        Show
        Dag H. Wanvik added a comment - Hi Kim, uploading a diff with for the localization files. If you apply it, you should be able to see that the texts have changed by removing the characters I indicated.
        Hide
        Kim Haase added a comment -

        Thanks, Dag! I will commit the first code patch, then apply and commit yours.

        Show
        Kim Haase added a comment - Thanks, Dag! I will commit the first code patch, then apply and commit yours.
        Hide
        Kim Haase added a comment -

        Committed patch DERBY-6061-code2.diff to code trunk at revision 1446656.

        Show
        Kim Haase added a comment - Committed patch DERBY-6061 -code2.diff to code trunk at revision 1446656.
        Hide
        Kim Haase added a comment -

        Actually, your patch is in a different format from mine, and the patch command doesn't seem to know what to do with it. What command do you use to apply patches that have diff commands inside them?

        Show
        Kim Haase added a comment - Actually, your patch is in a different format from mine, and the patch command doesn't seem to know what to do with it. What command do you use to apply patches that have diff commands inside them?
        Hide
        Kristian Waagan added a comment -

        Kim, did you try patch with -p1 instead of -p0?
        Looks like Dag uploaded a git patch, which (by default) has an extra directory prefix you have to strip off.

        Show
        Kristian Waagan added a comment - Kim, did you try patch with -p1 instead of -p0? Looks like Dag uploaded a git patch, which (by default) has an extra directory prefix you have to strip off.
        Hide
        Kim Haase added a comment -

        A-HA! Of course that's it. Thanks, Kristian! (I'll put that in my cheat sheet...)

        Show
        Kim Haase added a comment - A-HA! Of course that's it. Thanks, Kristian! (I'll put that in my cheat sheet...)
        Hide
        Kim Haase added a comment -

        Committed patch derby-6061-chinese.diff (thanks, Dag) to code trunk at revision 1446728.

        This issue can be reopened to make more properties file changes as needed.

        Show
        Kim Haase added a comment - Committed patch derby-6061-chinese.diff (thanks, Dag) to code trunk at revision 1446728. This issue can be reopened to make more properties file changes as needed.
        Hide
        Dag H. Wanvik added a comment -

        The Russian localization does not have that error message localized at all yet (08004.C.6), as well as 08004.C.3 and 08004.C.4 and others, I'm sure.
        Rick, has Russian been left behind?

        Show
        Dag H. Wanvik added a comment - The Russian localization does not have that error message localized at all yet (08004.C.6), as well as 08004.C.3 and 08004.C.4 and others, I'm sure. Rick, has Russian been left behind?
        Hide
        Myrna van Lunteren added a comment -

        The Russian, Czech, Hungarian and Polish language files were contributed by IBM a long time ago - but no further translations will be coming from that source. Oracle does not contribute translations for these languages.
        So yes, Russian and those other languages will fall further and further behind.

        Derby should pop up the English version for messages for which there is no translation in a particular locale.
        (Note that for this reason, if we change languages, we should remove the translation from these comatose language files. Better to get a correct English message than nonsense in the local locale.).

        Show
        Myrna van Lunteren added a comment - The Russian, Czech, Hungarian and Polish language files were contributed by IBM a long time ago - but no further translations will be coming from that source. Oracle does not contribute translations for these languages. So yes, Russian and those other languages will fall further and further behind. Derby should pop up the English version for messages for which there is no translation in a particular locale. (Note that for this reason, if we change languages, we should remove the translation from these comatose language files. Better to get a correct English message than nonsense in the local locale.).
        Hide
        Rick Hillegas added a comment -

        Hi Dag,

        What Myrna says is correct. Oracle (and before that, Sun) has been keeping the following localizations evergreen:

        Chinese (simplified and traditional)
        French
        German
        Italian
        Japanese
        Korean
        Spanish

        Thanks,
        -Rick

        Show
        Rick Hillegas added a comment - Hi Dag, What Myrna says is correct. Oracle (and before that, Sun) has been keeping the following localizations evergreen: Chinese (simplified and traditional) French German Italian Japanese Korean Spanish Thanks, -Rick
        Hide
        Kim Haase added a comment -

        Closing, since changes have appeared in Latest Alpha Manuals.

        Show
        Kim Haase added a comment - Closing, since changes have appeared in Latest Alpha Manuals.

          People

          • Assignee:
            Kim Haase
            Reporter:
            Kim Haase
          • Votes:
            0 Vote for this issue
            Watchers:
            7 Start watching this issue

            Dates

            • Created:
              Updated:
              Resolved:

              Development