Derby
  1. Derby
  2. DERBY-2227

Web Site - Add Checklist page for Doc updates for each release

    Details

    • Type: Improvement Improvement
    • Status: Closed
    • Priority: Minor Minor
    • Resolution: Fixed
    • Affects Version/s: None
    • Fix Version/s: 10.3.1.4
    • Component/s: Web Site
    • Labels:
      None

      Description

      Create a list of items to check and update for each release for the documentation.
      This list should include copywrite info, dates/time issues in the Working with Derby

      See this thread:
      http://www.nabble.com/Proposal---New-page-for-%22Release-Checklist-for-Docs%22-to-Derby-Doc-Web-Pages-%28WAS-Re%3A--jira--Commented%3A-%28DERBY-2194%29-A-few-more-problems-with-Working-with-Derby-manual-tf2947889.html

      1. docscheck.html
        8 kB
        Laura Stewart
      2. site.xml
        9 kB
        Laura Stewart
      3. Derby2227-1.diff
        9 kB
        Laura Stewart
      4. derby2227-1.zip
        30 kB
        Laura Stewart
      5. derby2227-2.diff
        9 kB
        Laura Stewart
      6. derby2227-2.zip
        9 kB
        Laura Stewart

        Activity

        Hide
        Laura Stewart added a comment -

        Updates committed and pushed to the web site.

        Show
        Laura Stewart added a comment - Updates committed and pushed to the web site.
        Hide
        Jean T. Anderson added a comment -

        Yes; the built pages must be committed. Step 8 at http://db.apache.org/derby/papers/derby_web.html suggests this:

        svn commit --message "here is my commit message" src build/site

        I usually put the commit info into a file called /tmp/changes.txt, then commit like this:

        svn commit --file /tmp/changes.txt src build/site

        You must commit the built changes because the built site is checked out of svn on people.apache.org. Step 9 then walks you through publishing the changes on people.apache.org.

        Show
        Jean T. Anderson added a comment - Yes; the built pages must be committed. Step 8 at http://db.apache.org/derby/papers/derby_web.html suggests this: svn commit --message "here is my commit message" src build/site I usually put the commit info into a file called /tmp/changes.txt, then commit like this: svn commit --file /tmp/changes.txt src build/site You must commit the built changes because the built site is checked out of svn on people.apache.org. Step 9 then walks you through publishing the changes on people.apache.org.
        Hide
        Laura Stewart added a comment -

        I understand why the build files are listed in the diff.
        So, I DO commit them as well as the src files, yes?

        Show
        Laura Stewart added a comment - I understand why the build files are listed in the diff. So, I DO commit them as well as the src files, yes?
        Hide
        Jean T. Anderson added a comment -

        This looks good, Laura, I just have one suggestion.

        Instead of this:
        Check with Apache for any updates to the copyright wording.

        Change it to this when you commit it:
        Check with derby-dev for any updates to the copyright wording.

        One tricky thing about committing web site changes is sometimes more pages get modified than you explicitly changed. This can be confusing. For example, you should see something like this below:

        $ svn stat src build/site
        M src/documentation/content/xdocs/manuals/docsfaq.xml
        A src/documentation/content/xdocs/manuals/docscheck.xml
        M src/documentation/content/xdocs/site.xml
        M build/site/linkmap.html
        M build/site/manuals/docsfaq.html
        M build/site/manuals/dita.html
        A build/site/manuals/docscheck.html
        M build/site/manuals/index.html
        M build/site/manuals/messages.html
        M build/site/manuals/guidelines.html

        More pages changed under build/site/manuals than what you explicitly changed because of your update to site.xml. Adding the new page, docscheck.xml, to the site menu causes the navigation to change for all pages on the documentation tab.

        I suggest you go ahead and commit.

        Show
        Jean T. Anderson added a comment - This looks good, Laura, I just have one suggestion. Instead of this: Check with Apache for any updates to the copyright wording. Change it to this when you commit it: Check with derby-dev for any updates to the copyright wording. One tricky thing about committing web site changes is sometimes more pages get modified than you explicitly changed. This can be confusing. For example, you should see something like this below: $ svn stat src build/site M src/documentation/content/xdocs/manuals/docsfaq.xml A src/documentation/content/xdocs/manuals/docscheck.xml M src/documentation/content/xdocs/site.xml M build/site/linkmap.html M build/site/manuals/docsfaq.html M build/site/manuals/dita.html A build/site/manuals/docscheck.html M build/site/manuals/index.html M build/site/manuals/messages.html M build/site/manuals/guidelines.html More pages changed under build/site/manuals than what you explicitly changed because of your update to site.xml. Adding the new page, docscheck.xml, to the site menu causes the navigation to change for all pages on the documentation tab. I suggest you go ahead and commit.
        Hide
        Laura Stewart added a comment -

        Updated the Documentation Web site files per comments received.
        Included in the zip file Derby2227-2.zip are the html pages that were updated and
        the site.xml file that was updated.

        Show
        Laura Stewart added a comment - Updated the Documentation Web site files per comments received. Included in the zip file Derby2227-2.zip are the html pages that were updated and the site.xml file that was updated.
        Hide
        Laura Stewart added a comment -

        I am almost ready to commit the updates to the Derby Web site.
        I plan to use the steps to commit these changes as documented
        here:
        http://db.apache.org/derby/papers/derby_web.html#Updating+the+Apache+Derby+web+site
        Is there anything "tricky" that I should know before I proceed to commit these updates that I generated?

        Show
        Laura Stewart added a comment - I am almost ready to commit the updates to the Derby Web site. I plan to use the steps to commit these changes as documented here: http://db.apache.org/derby/papers/derby_web.html#Updating+the+Apache+Derby+web+site Is there anything "tricky" that I should know before I proceed to commit these updates that I generated?
        Hide
        Jean T. Anderson added a comment -

        I think "licencing" should be "licensing".
        Are these missing closing quotes?

        "copyryear year="2002,2006"
        copyryear year="2002,2007

        It might be helpful to add a link to http://wiki.apache.org/db-derby/DerbySnapshotOrRelease as the higher level writeup on what needs to be done for releases.

        Show
        Jean T. Anderson added a comment - I think "licencing" should be "licensing". Are these missing closing quotes? "copyryear year="2002,2006" copyryear year="2002,2007 It might be helpful to add a link to http://wiki.apache.org/db-derby/DerbySnapshotOrRelease as the higher level writeup on what needs to be done for releases.
        Hide
        Laura Stewart added a comment -

        I have attached a patch file (derby2227-1.diff) that contains the new page "docscheck" which is
        a Release Checklist for Documentation. I have also attached a zip file that contains the site.xml file and
        the html pages for all of the Doc Web pages.

        In addition to creating the checklist, I also added a item to the FAQ page about the proper terminology to use
        when talking about parts of SQL statements. This issue came up as part of Derby-2240.
        See this thread:
        http://www.nabble.com/Questionable-use-of-word-in-%22VALUES-expression%22-of-Derby-Reference-Manual-tf2971886.html

        Please look over these pages and let me know if there is anything that needs to be changed.

        Show
        Laura Stewart added a comment - I have attached a patch file (derby2227-1.diff) that contains the new page "docscheck" which is a Release Checklist for Documentation. I have also attached a zip file that contains the site.xml file and the html pages for all of the Doc Web pages. In addition to creating the checklist, I also added a item to the FAQ page about the proper terminology to use when talking about parts of SQL statements. This issue came up as part of Derby-2240. See this thread: http://www.nabble.com/Questionable-use-of-word-in-%22VALUES-expression%22-of-Derby-Reference-Manual-tf2971886.html Please look over these pages and let me know if there is anything that needs to be changed.
        Hide
        Jean T. Anderson added a comment -

        And one MORE clarification. Where I wrote:

        > The ASF source header policy [1] requires that a source file NOT have a copyright statement in it;

        I meant that the source file must not have an ASF copyright statement (the ASF copyright belongs in the NOTICE file). It's possible for a source file to have have non-ASF copyright statements in it. Lots of details are in [1].

        [1] http://www.apache.org/legal/src-headers.html

        Show
        Jean T. Anderson added a comment - And one MORE clarification. Where I wrote: > The ASF source header policy [1] requires that a source file NOT have a copyright statement in it; I meant that the source file must not have an ASF copyright statement (the ASF copyright belongs in the NOTICE file). It's possible for a source file to have have non-ASF copyright statements in it. Lots of details are in [1] . [1] http://www.apache.org/legal/src-headers.html
        Hide
        Jean T. Anderson added a comment -

        Here's more clarification because this can be kind of confusing....

        We need to separate the issues of "source" from "built product" because the ASF requirements are different.

        The ASF source header policy [1] requires that a source file NOT have a copyright statement in it; it should have the header specified in [1]. There was a flurry of activity before 10.2.1.6 was released to update derby source (DERBY-1377, DERBY-1422). The copyright goes into the NOTICE file instead.

        The answer for [1]'s FAQ "What if my project includes its web site within a product distribution?" covers all documentation (not just web site):
        > Documentation, including web site documentation distributed with the release, may include the header text within some form of metadata (such as HTML comments) or as a header or footer appearing in the visible documentation.

        So that's the source file policy.

        For the built and distributed "product", things aren't quite so cut and dried from my read. Look at the FAQ for [1]: "Does this policy also apply to content displayed on our web sites?" The answer is currently "no". At some point, a "terms of use" link might be added to web site pges.

        ASF guidelines for how to form the copyright statement are covered in [2].

        I don't think that a copyright needs to appear on each displayed page, but that discussion might be better moved to DERBY-2237.

        [1] http://www.apache.org/legal/src-headers.html
        [2] http://www.apache.org/dev/apply-license.html

        Show
        Jean T. Anderson added a comment - Here's more clarification because this can be kind of confusing.... We need to separate the issues of "source" from "built product" because the ASF requirements are different. The ASF source header policy [1] requires that a source file NOT have a copyright statement in it; it should have the header specified in [1] . There was a flurry of activity before 10.2.1.6 was released to update derby source ( DERBY-1377 , DERBY-1422 ). The copyright goes into the NOTICE file instead. The answer for [1] 's FAQ "What if my project includes its web site within a product distribution?" covers all documentation (not just web site): > Documentation, including web site documentation distributed with the release, may include the header text within some form of metadata (such as HTML comments) or as a header or footer appearing in the visible documentation. So that's the source file policy. For the built and distributed "product", things aren't quite so cut and dried from my read. Look at the FAQ for [1] : "Does this policy also apply to content displayed on our web sites?" The answer is currently "no". At some point, a "terms of use" link might be added to web site pges. ASF guidelines for how to form the copyright statement are covered in [2] . I don't think that a copyright needs to appear on each displayed page, but that discussion might be better moved to DERBY-2237 . [1] http://www.apache.org/legal/src-headers.html [2] http://www.apache.org/dev/apply-license.html
        Hide
        Kim Haase added a comment -

        > The copyright year should change only if files in that book have changed in actual content (not just formatting). The date is a begin,end range. So, for a book whose files have changed in 2007, it would be:
        >
        > <copyryear year="2004, 2007"/>
        >
        > If you find yourself changing files in a given book, I suggest you go ahead and update the date – don't wait for a release.
        >
        > Does the copyryear tag ever get used? --I think the copyright should only be visible on the copyright page of each book.

        It seems to be used once at the beginning of the monohtml books, but I can't be sure; the value might be hardcoded instead. Coincidentally, DERBY-2237 was just now filed, presumably to fix the following problems: 1) in the PDF books, the word "Copyright", but nothing else, appears at the top of every page; 2) in the monohtml books, "Copyright" by itself appears three times near the beginning of the book.

        I like your suggestion that instead of the proposed fix to DERBY-2237, the word "Copyright" should not appear at all; instead, the copyright page, which appears in all three forms of each book, should be the sole location of the copyright info.

        Show
        Kim Haase added a comment - > The copyright year should change only if files in that book have changed in actual content (not just formatting). The date is a begin,end range. So, for a book whose files have changed in 2007, it would be: > > <copyryear year="2004, 2007"/> > > If you find yourself changing files in a given book, I suggest you go ahead and update the date – don't wait for a release. > > Does the copyryear tag ever get used? --I think the copyright should only be visible on the copyright page of each book. It seems to be used once at the beginning of the monohtml books, but I can't be sure; the value might be hardcoded instead. Coincidentally, DERBY-2237 was just now filed, presumably to fix the following problems: 1) in the PDF books, the word "Copyright", but nothing else, appears at the top of every page; 2) in the monohtml books, "Copyright" by itself appears three times near the beginning of the book. I like your suggestion that instead of the proposed fix to DERBY-2237 , the word "Copyright" should not appear at all; instead, the copyright page, which appears in all three forms of each book, should be the sole location of the copyright info.
        Hide
        Jean T. Anderson added a comment -

        For this question:

        > Another copyright-related item: each ditamap file has a <copyryear> tag that needs to be updated. It would be helpful to know the policy for this. Currently the tag says:
        >
        > <copyryear year="2004, 2006"/>
        >
        > Is this tag modified only when Derby has a point release (if that's the term) – that is, it goes from 10.0 to 10.1, 10.1 to 10.2 etc.? And is the new number added to the list – that is, nothing is removed? So assuming 10.3 comes out this year, it will need to say "2004, 2006, 2007"?

        The copyright year should change only if files in that book have changed in actual content (not just formatting). The date is a begin,end range. So, for a book whose files have changed in 2007, it would be:

        <copyryear year="2004, 2007"/>

        If you find yourself changing files in a given book, I suggest you go ahead and update the date – don't wait for a release.

        Does the copyryear tag ever get used? --I think the copyright should only be visible on the copyright page of each book.

        Show
        Jean T. Anderson added a comment - For this question: > Another copyright-related item: each ditamap file has a <copyryear> tag that needs to be updated. It would be helpful to know the policy for this. Currently the tag says: > > <copyryear year="2004, 2006"/> > > Is this tag modified only when Derby has a point release (if that's the term) – that is, it goes from 10.0 to 10.1, 10.1 to 10.2 etc.? And is the new number added to the list – that is, nothing is removed? So assuming 10.3 comes out this year, it will need to say "2004, 2006, 2007"? The copyright year should change only if files in that book have changed in actual content (not just formatting). The date is a begin,end range. So, for a book whose files have changed in 2007, it would be: <copyryear year="2004, 2007"/> If you find yourself changing files in a given book, I suggest you go ahead and update the date – don't wait for a release. Does the copyryear tag ever get used? --I think the copyright should only be visible on the copyright page of each book.
        Hide
        Kim Haase added a comment -

        For the second section, the specific Working with Derby files that need to have the dates updated are:

        twwdactivity1.dita
        twwdactivity2.dita
        twwdactivity3_Setup.dita
        twwdactivity4.dita

        Also, the following Working with Derby files also have specific Derby release and tag values that need to be updated:

        twwdactivity1.dita
        twwdactivity2.dita
        twwdactivity4.dita

        Another copyright-related item: each ditamap file has a <copyryear> tag that needs to be updated. It would be helpful to know the policy for this. Currently the tag says:

        <copyryear year="2004, 2006"/>

        Is this tag modified only when Derby has a point release (if that's the term) – that is, it goes from 10.0 to 10.1, 10.1 to 10.2 etc.? And is the new number added to the list – that is, nothing is removed? So assuming 10.3 comes out this year, it will need to say "2004, 2006, 2007"?

        About the conrefs files section – you might note that if a new book is added to the Derby doc set, it needs to be added to the "pub" section of each conrefs file. I notice that Working with Derby has been added only to the conrefs file for the Tools manual – presumably because that book refers to it but the others don't.

        There are two other files with 2006 in them:

        devguide/cdevdvlp27715.dita
        ref/rrefdayfunc.dita

        Show
        Kim Haase added a comment - For the second section, the specific Working with Derby files that need to have the dates updated are: twwdactivity1.dita twwdactivity2.dita twwdactivity3_Setup.dita twwdactivity4.dita Also, the following Working with Derby files also have specific Derby release and tag values that need to be updated: twwdactivity1.dita twwdactivity2.dita twwdactivity4.dita Another copyright-related item: each ditamap file has a <copyryear> tag that needs to be updated. It would be helpful to know the policy for this. Currently the tag says: <copyryear year="2004, 2006"/> Is this tag modified only when Derby has a point release (if that's the term) – that is, it goes from 10.0 to 10.1, 10.1 to 10.2 etc.? And is the new number added to the list – that is, nothing is removed? So assuming 10.3 comes out this year, it will need to say "2004, 2006, 2007"? About the conrefs files section – you might note that if a new book is added to the Derby doc set, it needs to be added to the "pub" section of each conrefs file. I notice that Working with Derby has been added only to the conrefs file for the Tools manual – presumably because that book refers to it but the others don't. There are two other files with 2006 in them: devguide/cdevdvlp27715.dita ref/rrefdayfunc.dita
        Hide
        Jean T. Anderson added a comment -

        Dan is correct.

        Show
        Jean T. Anderson added a comment - Dan is correct. Each dita source file should contain the ASF header as documented at http://www.apache.org/legal/src-headers.html . Each book has a copyright page at the front, and the date should be updated if needed.
        Hide
        Daniel John Debrunner added a comment -

        The propose page has ithis statement on "copywrite" (sic):

        "Each new dita file that is created must contain copywrite information at the top of the file."

        I think it should be "licensing information", not "copywrite information".

        The ASF policy on source headers forbids copyright information in source files.

        http://www.apache.org/legal/src-headers.html

        Show
        Daniel John Debrunner added a comment - The propose page has ithis statement on "copywrite" (sic): "Each new dita file that is created must contain copywrite information at the top of the file." I think it should be "licensing information", not "copywrite information". The ASF policy on source headers forbids copyright information in source files. http://www.apache.org/legal/src-headers.html
        Hide
        Laura Stewart added a comment -

        I have prepared a preliminary draft of the new Web page for Documentation.
        The page name is "Release Checklist for Docs".
        Please look over the content and let me know what needs to be corrected,/added.

        I will post a formal patch/diff file after I receive your comments.

        Show
        Laura Stewart added a comment - I have prepared a preliminary draft of the new Web page for Documentation. The page name is "Release Checklist for Docs". Please look over the content and let me know what needs to be corrected,/added. I will post a formal patch/diff file after I receive your comments.

          People

          • Assignee:
            Laura Stewart
            Reporter:
            Laura Stewart
          • Votes:
            0 Vote for this issue
            Watchers:
            0 Start watching this issue

            Dates

            • Created:
              Updated:
              Resolved:

              Development