xdocs/dev-eclipse-plugin-signing.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>Signing Eclipse Plugins - release process</title>
 <author email="dev@uima.apache.org">
  Apache UIMA Documentation Team</author>
 </properties>

 <body>
 <section name="Overview">
 <p>All released Apache artifacts are normally signed.  Eclipse jar signing is in addition
 to the Apache release signing.  This additional signing (with a recognized authority certificate)
 allows the Eclipse installer to avoid saying it is installing unsigned artifacts and needs permission to continue.
 </p>

 <p>
 It also enables automatic notification and subsequent update (if the user chooses) of upgrades.  Because of this,
 insure your feature id's are different for versions which should not automatically update.
 </p>

 <p>Both the feature jars and the plugin jars need to be signed.  But not the pack.gz things or the artifacts / contents jars.</p>

   <subsection name="Process Flow">
     <p>We use a 2 step process, to reduce costs to Apache for signing release candidates which subsequently fail.
        After the release vote passes, feature and plugin Jar files (but not the pack.gz files) are manually uploaded and signed,
        and then a subsequent maven task is run to rebuild just the site packaging artifacts using the signed Jars.</p>

     <p>The first step is to do a normal build of the update site, using mvn release:prepare.
        This produces the artifacts for voting on, without jar-signing the
        new Jars, and writes the "tag" for this into SVN for record keeping.</p>

      <p>After the vote passes
        the release manager, using their special credentials, logs onto the signing portal.  This process
        requires a one-time code, which the portal will send to you.</p>

        <p style="margin-left: 40px">(Note: I had to refresh my web browser in order to
        get the screen showing that option).
        </p>

        <p>Once signed, in, make a signing set
        consisting of all of the Jars in target/eus-work/plugins and feature jars (feature jars must also be signed)
        (not the *.pack.gz files, nor the  ..content nor ..artifact metadata Jars).
        </p>

        <p>For convenience, and to rename any name-collisions between jars in the features/ and plugins/ directories,
           make a new folder (signingSet), and copy all the files from target/saved into that, renaming any
           collisions.
        </p>

        <p>On the signing web application make a new signing set and upload these files to that set.
        Then sign them (either use Test signing or Production signing).  Test signing is only if you're new to
        the whole process and want to test things work.  Then download the result, and copy them into the
        target/eus-work/features and /plugins directories, overlaying the unsigned ones.</p>

      <p>Then rebuild the update site by running <code>mvn antrun:run@make-subsite-after-signing</code>.
         This does the remaining steps,
         including packing (regenerating the .pack.gz files in the /plugins) and adding the various
         signatures and checksums to these.  These are then re-published, merging with any previous contents of the update site.
         </p>

      <p>Messages about "Artifact repository out of sync. Overwriting xxxx" are to be expected.</p>

      <p>Please try installing the result to confirm nothing went wrong in this re-build process.</p>

      <p>If you used a test signing, instead of a production signing,
      if all is well, repeat the above process starting with selection "production" signing for the jars, downloading
      those jars, replacing them into the eus-work directory, and re-running the mvn antrun:run@make-subsite-after-signing.</p>

   </subsection>
   <subsection name="Changes to Normal Build">
     <p>To support signing, the normal build needs some small changes.
       <ol>
         <li>(actually a bug fix) The existing build after running the JarProcessor, copies the original (unprocessed) Jars
             into the eus-work/plugins - accidentally overwriting the repacked/conditioned Jars.  This step must be deleted;
             in order to have the processed/conditioned Jars available for signing.
         </li>
         <li>When doing the subsite build, any previous versions are combined with the new version.  This is done by
             downloading the previous versions into a new instance of the subsite.  Because this packaging step needs
             to be redone, the original contents.jar and artifacts.jar files need to be saved so they can be restored
             before the rebuild with signed artifacts.</li>
       </ol>
     </p>
     <p>Additionally, to aid in reproducing things, the pre-signed, conditioned JARs are saved; in case of need, they can
       be restored without rebuilding them again.  This step might be removed in the future - it is not essential.</p>
   </subsection>
 </section>

 <section name="Release Manager needs to have a valid code signing certificate">
   <p>
     For the UIMA project, contact the PMC chair for aid in obtaining a code signing certificate if you need one.</p>
 </section>

 <section name="Release only if 1 or more changed Eclipse plugins">
   <p>If the release does not have any updates to Eclipse Plugin JARs, save Apache money by reusing previously released versions.
      If the release has 1 or more JARs, these will be signed in 1 signing event. so it doesn't matter how many Jars there are.</p>
 </section>

 <section name="Links to Apache resources for codesigning">
   <p>See <a target="_blank" rel="noopener" href="https://reference.apache.org/pmc/codesigning">
   https://reference.apache.org/pmc/codesigning</a> for general information.
   </p>
   <p>See <a target="_blank" rel="noopener" href="https://wiki.eclipse.org/JAR_Signing#What_gets_signed">
   https://wiki.eclipse.org/JAR_Signing#What_gets_signed</a> for background on signing Eclipse Plugins.</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>Signing Eclipse Plugins - release process</title>
	<author email="dev@uima.apache.org">
	Apache UIMA Documentation Team</author>
	</properties>

	<body>
	<section name="Overview">
	<p>All released Apache artifacts are normally signed. Eclipse jar signing is in addition
	to the Apache release signing. This additional signing (with a recognized authority certificate)
	allows the Eclipse installer to avoid saying it is installing unsigned artifacts and needs permission to continue.
	</p>

	<p>
	It also enables automatic notification and subsequent update (if the user chooses) of upgrades. Because of this,
	insure your feature id's are different for versions which should not automatically update.
	</p>

	<p>Both the feature jars and the plugin jars need to be signed. But not the pack.gz things or the artifacts / contents jars.</p>

	<subsection name="Process Flow">
	<p>We use a 2 step process, to reduce costs to Apache for signing release candidates which subsequently fail.
	After the release vote passes, feature and plugin Jar files (but not the pack.gz files) are manually uploaded and signed,
	and then a subsequent maven task is run to rebuild just the site packaging artifacts using the signed Jars.</p>

	<p>The first step is to do a normal build of the update site, using mvn release:prepare.
	This produces the artifacts for voting on, without jar-signing the
	new Jars, and writes the "tag" for this into SVN for record keeping.</p>

	<p>After the vote passes
	the release manager, using their special credentials, logs onto the signing portal. This process
	requires a one-time code, which the portal will send to you.</p>

	<p style="margin-left: 40px">(Note: I had to refresh my web browser in order to
	get the screen showing that option).
	</p>

	<p>Once signed, in, make a signing set
	consisting of all of the Jars in target/eus-work/plugins and feature jars (feature jars must also be signed)
	(not the *.pack.gz files, nor the ..content nor ..artifact metadata Jars).
	</p>

	<p>For convenience, and to rename any name-collisions between jars in the features/ and plugins/ directories,
	make a new folder (signingSet), and copy all the files from target/saved into that, renaming any
	collisions.
	</p>

	<p>On the signing web application make a new signing set and upload these files to that set.
	Then sign them (either use Test signing or Production signing). Test signing is only if you're new to
	the whole process and want to test things work. Then download the result, and copy them into the
	target/eus-work/features and /plugins directories, overlaying the unsigned ones.</p>

	<p>Then rebuild the update site by running <code>mvn antrun:run@make-subsite-after-signing</code>.
	This does the remaining steps,
	including packing (regenerating the .pack.gz files in the /plugins) and adding the various
	signatures and checksums to these. These are then re-published, merging with any previous contents of the update site.
	</p>

	<p>Messages about "Artifact repository out of sync. Overwriting xxxx" are to be expected.</p>

	<p>Please try installing the result to confirm nothing went wrong in this re-build process.</p>

	<p>If you used a test signing, instead of a production signing,
	if all is well, repeat the above process starting with selection "production" signing for the jars, downloading
	those jars, replacing them into the eus-work directory, and re-running the mvn antrun:run@make-subsite-after-signing.</p>

	</subsection>
	<subsection name="Changes to Normal Build">
	<p>To support signing, the normal build needs some small changes.
	<ol>
	<li>(actually a bug fix) The existing build after running the JarProcessor, copies the original (unprocessed) Jars
	into the eus-work/plugins - accidentally overwriting the repacked/conditioned Jars. This step must be deleted;
	in order to have the processed/conditioned Jars available for signing.
	</li>
	<li>When doing the subsite build, any previous versions are combined with the new version. This is done by
	downloading the previous versions into a new instance of the subsite. Because this packaging step needs
	to be redone, the original contents.jar and artifacts.jar files need to be saved so they can be restored
	before the rebuild with signed artifacts.</li>
	</ol>
	</p>
	<p>Additionally, to aid in reproducing things, the pre-signed, conditioned JARs are saved; in case of need, they can
	be restored without rebuilding them again. This step might be removed in the future - it is not essential.</p>
	</subsection>
	</section>

	<section name="Release Manager needs to have a valid code signing certificate">
	<p>
	For the UIMA project, contact the PMC chair for aid in obtaining a code signing certificate if you need one.</p>
	</section>

	<section name="Release only if 1 or more changed Eclipse plugins">
	<p>If the release does not have any updates to Eclipse Plugin JARs, save Apache money by reusing previously released versions.
	If the release has 1 or more JARs, these will be signed in 1 signing event. so it doesn't matter how many Jars there are.</p>
	</section>

	<section name="Links to Apache resources for codesigning">
	<p>See <a target="_blank" rel="noopener" href="https://reference.apache.org/pmc/codesigning">
	https://reference.apache.org/pmc/codesigning</a> for general information.
	</p>
	<p>See <a target="_blank" rel="noopener" href="https://wiki.eclipse.org/JAR_Signing#What_gets_signed">
	https://wiki.eclipse.org/JAR_Signing#What_gets_signed</a> for background on signing Eclipse Plugins.</p>
	</section>

	</body>
	</document>