xdocs/dev-eclipse-plugin-archiving.xml - uima-site - Git at Google

 <?xml version="1.0" encoding="ISO-8859-1"?>
 <!--
 Licensed to the Apache Software Foundation (ASF) under one
 or more contributor license agreements.  See the NOTICE file
 distributed with this work for additional information
 regarding copyright ownership.  The ASF licenses this file
  to you under the Apache License, Version 2.0 (the
 "License"); you may not use this file except in compliance
 with the License.  You may obtain a copy of the License at

   https://www.apache.org/licenses/LICENSE-2.0

 Unless required by applicable law or agreed to in writing,
 software distributed under the License is distributed on an
 "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 KIND, either express or implied.  See the License for the
 specific language governing permissions and limitations
 under the License.
 -->
 <document>

 <properties>
 <title>Archiving Eclipse Plugins</title>
 <author email="dev@uima.apache.org">
  Apache UIMA Documentation Team</author>
 </properties>

 <body>
 <section name="Overview">
 <p>The Eclipse Update Site holds a multi-update-site root, which, in turn, links to various subsites (for various projects).
   Each of those subsites typically has several versions of the plugins; a release process adds fresh versions of plugins to that site.
 </p>

 <p>At some point, there are too many versions, and it makes sense to archive these older ones.
 </p>

 </section>

 <section name="Goals for archiving">
   <p>An archive approach would, ideally, have these properties</p>
   <ul>
     <li>Reduce the number of choices during the Eclipse install menus to just the more recent ones</li>
     <li>Support an older "archive" site where older version could be obtained if needed, without loading the Apache Mirror system.</li>
     <li>Have a simple mechanism for archiving older releases</li>
   </ul>
 </section>

 <section name="Strategy for archiving">
   <p>The basic strategy is to have multiple update sites:
   <ul><li>A more-or-less current one, which has the most recent plugins, plus perhaps a few of the older releases</li>
       <li>Older plugin site(s) (not too many) which contain ranges of plugins</li>
   </ul>
   </p>

   <p>A typical imagined timeline would be
     <ul>
       <li>A subsite is started (e.g. ruta, or uimaj)</li>
       <li>Releases occur, and plugins are added at some version level</li>
       <li>After some number of releases, a decision is made that the repo is getting too big.</li>

       <li>The old repo is renamed with a suffix indicating the range of versions in it.  For example,
          the "uimaj" repo might have a name uimaj-2.3.1-2.10.1.</li>
       <li>A new repo is created, with just one (the latest version), and is deployed.
         The uima website
         documentation indicates where to find older eclipse plugins (the Apache archive site, following the
         the naming conventions: uima/archive-eclipse-update-site/subsitename/subsitename-x.x.x-y.y.y).</li>
       <li>After confirming that the renamed old site is visible in Archive, then it is deleted on the main release site.</li>
     </ul>
   </p>

   <p>After this is done, the new subsite will have just the latest version in it,
   and would then be added to over time, with additional
      releases.  When it gets too big, the same procedure is repeated, with a new named update site .../---subsitename.u.u.u-v.v.v
      with another range set being created and archived.</p>

 </section>

 <section name="Naming convention and locations">
   <p>The archives are stored using this naming convention:</p>

   <ul>
     <li>Root location: <br/><br></br><code>uima/archive-eclipse-update-site/[particular-archive-name]</code></li>
     <br/>
     <li>The particular-archive-name is named <br/> <br/><code>subsite-name-x.x.x-y.y.y</code>,
       where the x.x.x is the first version in the archive, and y.y.y is the last one.</li>
   </ul>
 </section>

 <section name="Resetting the update site for a new batch of versions">
   <!--
   <p>The eclipse ant tasks for maintaining update sites are documented here:
   https://help.eclipse.org/oxygen/index.jsp?topic=%2Forg.eclipse.platform.doc.isv%2Fguide%2Fp2_repositorytasks.htm .
   </p>

   <p>This ant task is used in a Maven project, located in uima/build, named:
     <a target="_blank" rel="noopener" href="https://svn.apache.org/repos/asf/uima/build/trunk/uima-eclipse-update-site-slicing/">
     uima-eclipse-update-site-slicing</a>.
     This does the slicing described above.  To use, check out this project as a maven project (it's not a Java project), and
     read the readme.txt, and follow the instructions.</p>

   <p>When it runs, it reads the existing subsite directly from the dist.apache.org repository, and builds the request slice
     in the project's target/eclipse-update-site/- - -subsite- - - directory.</p>

   <p>To complete the maintenance, do these steps in the dist.apache.org svn release eclipse-update-site:
     <ol>
       <li>Do a sanity test of the new subsite - try installing it into a fresh Eclipse install.</li>
       <li>svn mv  to rename the current subsite to the versioned name.</li>
       <li>once it appears on the archive spot, do an svn delete to remove it </li>
       <li>import the new (pruned) subsite to the release spot.</li>
     </ol></p>
     -->
   <p>Here is the procedure to reset the update site for a new batch of versions, going forward.
   <ul>
     <li>In the dist.apache.org svn for release, copy the to-be-reset update subsite to the new archive spot.
       Example:

       <br/><br/>
       svn copy -m "create eclipse plugin archive for uimaj-2.3.1-2.10.1"
           https://dist.apache.org/repos/dist/release/uima/eclipse-update-site/uimaj
           https://dist.apache.org/repos/dist/release/uima/archive-eclipse-update-site/uimaj-2.3.1-2.10.1</li>

     <li>wait for this to appear on the archive site, e.g.
         https://archive.apache.org/dist/uima/archive-eclipse-update-site/uimaj-2.3.1-2.10.1</li>

     <li>delete from the main site. Example:

       <br/><br/>
       svn delete -m "create eclipse plugin archive for uimaj-2.3.1-2.10.1 delete in main mirror"
           https://dist.apache.org/repos/dist/release/uima/archive-eclipse-update-site/uimaj-2.3.1-2.10.1</li>

     <li>reset the main update subsite: best way is to delete it and then re-import it.  Example:

       <br/><br/>
       svn delete -m "reset main Eclipse update subsite for uimaj - delete old one"
           https://dist.apache.org/repos/dist/release/uima/eclipse-update-site/uimaj

       <br/><br/>
       cd to import directory, eg. uimaj-eclipse-update-site/target/eclipse-update-site/uimaj
       svn import -m "reset main Eclipse update subsite" . https://dist.apache.org/repos/dist/release/uima/eclipse-update-site/uimaj

     </li>

   </ul>

 </p>
 </section>

 </body>
 </document>
	<?xml version="1.0" encoding="ISO-8859-1"?>
	<!--
	Licensed to the Apache Software Foundation (ASF) under one
	or more contributor license agreements. See the NOTICE file
	distributed with this work for additional information
	regarding copyright ownership. The ASF licenses this file
	to you under the Apache License, Version 2.0 (the
	"License"); you may not use this file except in compliance
	with the License. You may obtain a copy of the License at

	https://www.apache.org/licenses/LICENSE-2.0

	Unless required by applicable law or agreed to in writing,
	software distributed under the License is distributed on an
	"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
	KIND, either express or implied. See the License for the
	specific language governing permissions and limitations
	under the License.
	-->
	<document>

	<properties>
	<title>Archiving Eclipse Plugins</title>
	<author email="dev@uima.apache.org">
	Apache UIMA Documentation Team</author>
	</properties>

	<body>
	<section name="Overview">
	<p>The Eclipse Update Site holds a multi-update-site root, which, in turn, links to various subsites (for various projects).
	Each of those subsites typically has several versions of the plugins; a release process adds fresh versions of plugins to that site.
	</p>

	<p>At some point, there are too many versions, and it makes sense to archive these older ones.
	</p>

	</section>

	<section name="Goals for archiving">
	<p>An archive approach would, ideally, have these properties</p>
	<ul>
	<li>Reduce the number of choices during the Eclipse install menus to just the more recent ones</li>
	<li>Support an older "archive" site where older version could be obtained if needed, without loading the Apache Mirror system.</li>
	<li>Have a simple mechanism for archiving older releases</li>
	</ul>
	</section>

	<section name="Strategy for archiving">
	<p>The basic strategy is to have multiple update sites:
	<ul><li>A more-or-less current one, which has the most recent plugins, plus perhaps a few of the older releases</li>
	<li>Older plugin site(s) (not too many) which contain ranges of plugins</li>
	</ul>
	</p>

	<p>A typical imagined timeline would be
	<ul>
	<li>A subsite is started (e.g. ruta, or uimaj)</li>
	<li>Releases occur, and plugins are added at some version level</li>
	<li>After some number of releases, a decision is made that the repo is getting too big.</li>

	<li>The old repo is renamed with a suffix indicating the range of versions in it. For example,
	the "uimaj" repo might have a name uimaj-2.3.1-2.10.1.</li>
	<li>A new repo is created, with just one (the latest version), and is deployed.
	The uima website
	documentation indicates where to find older eclipse plugins (the Apache archive site, following the
	the naming conventions: uima/archive-eclipse-update-site/subsitename/subsitename-x.x.x-y.y.y).</li>
	<li>After confirming that the renamed old site is visible in Archive, then it is deleted on the main release site.</li>
	</ul>
	</p>

	<p>After this is done, the new subsite will have just the latest version in it,
	and would then be added to over time, with additional
	releases. When it gets too big, the same procedure is repeated, with a new named update site .../---subsitename.u.u.u-v.v.v
	with another range set being created and archived.</p>

	</section>

	<section name="Naming convention and locations">
	<p>The archives are stored using this naming convention:</p>

	<ul>
	<li>Root location: <br/><br></br><code>uima/archive-eclipse-update-site/[particular-archive-name]</code></li>
	<br/>
	<li>The particular-archive-name is named <br/> <br/><code>subsite-name-x.x.x-y.y.y</code>,
	where the x.x.x is the first version in the archive, and y.y.y is the last one.</li>
	</ul>
	</section>

	<section name="Resetting the update site for a new batch of versions">
	<!--
	<p>The eclipse ant tasks for maintaining update sites are documented here:
	https://help.eclipse.org/oxygen/index.jsp?topic=%2Forg.eclipse.platform.doc.isv%2Fguide%2Fp2_repositorytasks.htm .
	</p>

	<p>This ant task is used in a Maven project, located in uima/build, named:
	<a target="_blank" rel="noopener" href="https://svn.apache.org/repos/asf/uima/build/trunk/uima-eclipse-update-site-slicing/">
	uima-eclipse-update-site-slicing</a>.
	This does the slicing described above. To use, check out this project as a maven project (it's not a Java project), and
	read the readme.txt, and follow the instructions.</p>

	<p>When it runs, it reads the existing subsite directly from the dist.apache.org repository, and builds the request slice
	in the project's target/eclipse-update-site/- - -subsite- - - directory.</p>

	<p>To complete the maintenance, do these steps in the dist.apache.org svn release eclipse-update-site:
	<ol>
	<li>Do a sanity test of the new subsite - try installing it into a fresh Eclipse install.</li>
	<li>svn mv to rename the current subsite to the versioned name.</li>
	<li>once it appears on the archive spot, do an svn delete to remove it </li>
	<li>import the new (pruned) subsite to the release spot.</li>
	</ol></p>
	-->
	<p>Here is the procedure to reset the update site for a new batch of versions, going forward.
	<ul>
	<li>In the dist.apache.org svn for release, copy the to-be-reset update subsite to the new archive spot.
	Example:

	<br/><br/>
	svn copy -m "create eclipse plugin archive for uimaj-2.3.1-2.10.1"
	https://dist.apache.org/repos/dist/release/uima/eclipse-update-site/uimaj
	https://dist.apache.org/repos/dist/release/uima/archive-eclipse-update-site/uimaj-2.3.1-2.10.1</li>

	<li>wait for this to appear on the archive site, e.g.
	https://archive.apache.org/dist/uima/archive-eclipse-update-site/uimaj-2.3.1-2.10.1</li>

	<li>delete from the main site. Example:

	<br/><br/>
	svn delete -m "create eclipse plugin archive for uimaj-2.3.1-2.10.1 delete in main mirror"
	https://dist.apache.org/repos/dist/release/uima/archive-eclipse-update-site/uimaj-2.3.1-2.10.1</li>

	<li>reset the main update subsite: best way is to delete it and then re-import it. Example:

	<br/><br/>
	svn delete -m "reset main Eclipse update subsite for uimaj - delete old one"
	https://dist.apache.org/repos/dist/release/uima/eclipse-update-site/uimaj

	<br/><br/>
	cd to import directory, eg. uimaj-eclipse-update-site/target/eclipse-update-site/uimaj
	svn import -m "reset main Eclipse update subsite" . https://dist.apache.org/repos/dist/release/uima/eclipse-update-site/uimaj

	</li>

	</ul>

	</p>
	</section>

	</body>
	</document>