From commits-return-31995-apmail-directory-commits-archive=directory.apache.org@directory.apache.org Thu Jun 23 08:42:31 2011 Return-Path: X-Original-To: apmail-directory-commits-archive@www.apache.org Delivered-To: apmail-directory-commits-archive@www.apache.org Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by minotaur.apache.org (Postfix) with SMTP id 299FE429B for ; Thu, 23 Jun 2011 08:42:31 +0000 (UTC) Received: (qmail 16360 invoked by uid 500); 23 Jun 2011 08:42:31 -0000 Delivered-To: apmail-directory-commits-archive@directory.apache.org Received: (qmail 16299 invoked by uid 500); 23 Jun 2011 08:42:28 -0000 Mailing-List: contact commits-help@directory.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@directory.apache.org Delivered-To: mailing list commits@directory.apache.org Received: (qmail 16292 invoked by uid 99); 23 Jun 2011 08:42:27 -0000 Received: from nike.apache.org (HELO nike.apache.org) (192.87.106.230) by apache.org (qpsmtpd/0.29) with ESMTP; Thu, 23 Jun 2011 08:42:27 +0000 X-ASF-Spam-Status: No, hits=-1994.3 required=5.0 tests=ALL_TRUSTED,HTML_FONT_LOW_CONTRAST,HTML_MESSAGE,MIME_HTML_ONLY X-Spam-Check-By: apache.org Received: from [140.211.11.22] (HELO thor.apache.org) (140.211.11.22) by apache.org (qpsmtpd/0.29) with ESMTP; Thu, 23 Jun 2011 08:42:22 +0000 Received: from thor (localhost [127.0.0.1]) by thor.apache.org (8.13.8+Sun/8.13.8) with ESMTP id p5N8g0b7015559 for ; Thu, 23 Jun 2011 08:42:00 GMT Date: Thu, 23 Jun 2011 04:42:00 -0400 (EDT) From: confluence@apache.org To: commits@directory.apache.org Message-ID: <3679431.4474.1308818520161.JavaMail.confluence@thor> Subject: [CONF] Apache Directory Development > Releasing ApacheDS MIME-Version: 1.0 Content-Type: text/html; charset=UTF-8 Content-Transfer-Encoding: quoted-printable Auto-Submitted: auto-generated X-Virus-Checked: Checked by ClamAV on apache.org

Releasing ApacheDS

Page edited by Emmanuel L=C3=A9charny


Changes (60)

=20 =20
=20 <= /tr> = = <= /tr> =20
...
This will show you how to bui= ld and release the ApacheDS subproject. Keep an eye out for warning and no= te sections that show version specific differences in this process.
<= br>
h2. Manual Steps

Some things have not yet= been automated with maven and require users to manually edit some files. = Below are the steps to follow.

h3. Step (1): Update Version= s in MANIFEST.MF
h3. Update service/apacheds.sh and service/apacheds.bat

There is a manifest file in = the server-tools project which must be updated to reference the non-SNAPSHO= T release jars for daemon, shared and apacheds dependencies. Make sure the= right dependencies are present in this file.
Edit the apacheds.sh/bat files in the service project directory to up= date the revision numbers used in that file to reference non-SNAPSHOT relea= ses.

h3. Step (2): Update server-= main/apacheds.sh
h2. Release process

Edit the apacheds.sh file in= the server-main project directory to update the revision numbers used in t= hat file to reference non-SNAPSHOT releases.
Since we are using Nexus for releases the release process is as follo= ws (see also [http://www.apache.org/dev/publishing-maven-artifacts.html#sta= ging-maven]).

h3. Step (3): Update Version= s in server-installers/pom.xml

Edit the pom.xml file of the server= -installers module. Specifically the <svnBaseUrl> tag value must be = updated to reflect the position of the new tag to be created in subversion.= So if you have the following value for svnBaseUrl to release 1.0.2 of apa= cheds then change this line:

h3. 1. Test the Project
{noformat}
<svnBaseUrl>http://svn= .apache.org/repos/asf/directory/apacheds/branches/1.0</svnBaseUrl>
$ mvn release:prepare -DdryRun=3Dtrue
{noformat}

To:
Replace the version by the new version. Be careful, and remove the &#= 39;apacheds-parent-' which is proposed for the new tag. We should just = use the version number.

h3. 2. Deploy a Snapshot
{noformat}
<svnBaseUrl>http://svn= .apache.org/repos/asf/directory/apacheds/tags/1.0.2</svnBaseUrl>
=
$ mvn deploy
{noformat}

h3. Step (4): Update Version= s in Archetypes
This is useful to verify your settings in ~/.m2/settings.xml (Nexus p= assword and GPG key)

{info}
Presently these a= rchetypes do not exist for the 1.5 feature branch so this step may be skipp= ed.
{info}

There are two maven archetypes defined:

*= schema-archetype
* testcase-archetype

These archetypes are = modules inside the apacheds project folder in subversion. They contain two= files each which need to be massaged for the correct versions. These file= s are a simple shell script and the target pom.xml generated by these arche= types. Below the relative paths to these files are listed when inside the = apacheds folder:

| schema-archetype/apacheds-schema-archetype.sh |=
| schema-archetype/src/main/resources/archetype-resources/pom.xml | <= br>| testcase-archetype/apacheds-testcase-archetype.sh |
| testcase-arc= hetype/src/main/resources/archetype-resources/pom.xml |

Just open = up these files and you'll see places where version numbers are used. M= ake sure the proper versions are used in all cases. For example a snippet = from the schema-archetype pom.xml might look like so:

h3. 3. Prepare the Release
{noformat}
...
<dependencies&g= t;
<dependency>
<groupId>org.apache.directory= .server</groupId>
<artifactId>apacheds-core</artif= actId>
<version>1.0.2-SNAPSHOT</version>
&= lt;/dependency>
<dependency>
<groupId>org.= apache.directory.server</groupId>
<artifactId>apached= s-server-unit</artifactId>
<version>1.0.2-SNAPSHOT<= ;/version>
<scope>test</scope>
</depend= ency>
...
</dependencies>
...
$ mvn release:clean
$ mvn release:prepare
{noformat}

If you're releasing= 1.0.2 then just edit the versions to remove the -SNAPSHOT string.

{warning}
Sometimes you = won't see 1.0.2-SNAPSHOT if you're releasing 1.0.2. You might just= see 1.0.1 if we never edited this during the SHAPSHOT phase. So then you&= #39;ll see non-snapshot versions. Just put in the dependencies for the rel= ease.
{warning}
This creates a tag here: [http://svn.apache.org/viewvc/directory/apac= heds/tags/]

h3. Step (5): Editing RELEAS= E-NOTES.txt and README.txt

You might need to edit the RELEASE-NOT= ES.txt and README.txt files for things relavent to the release you're p= erforming.

h3. Step (6): Update Dependency Versions in Root POM =

Edit the root apacheds/pom.xml and make sure all dependencies are = using non-SNAPSHOT versions. If you just released shared and daemon you'= ;ll want to update these. Also take a look at the <dependencyManagement= > section to see if anything needs to be updated for the present release= . Remember no SNAPSHOTs.

h3. Step (7): Update NOTICE.txt and LICE= NSE.txt Files

If you added any new libraries which require an upda= te of the NOTICE.txt and LICENSE.txt files do so now in the server-installe= rs directory.

h2. Releasing Maven Artifacts

{warning} <= br>If you just released and deployed new shared and daemon projects needed = by this apacheds release you're about to perform then you must make sur= e it happened on the same machine or else you need to build the shared and = daemon project tags. The reason for this is that replication time is neede= d for the shared and daemon project jars to reach ibiblio. If you build th= ese dependent projects on the same machine that you're about to build a= pacheds on then you will have the required release jars in your local repos= itory and maven will not need to hit ibiblio.
{warning}

For th= ese examples we'll presume a release (1.0.2) on the 1.0 branch of apach= eds. For releases on the trunk or on other branches change the svn checkout= line to accomodate.

h3. 4. Stage the Release
{noformat}
$ svn co https://svn.apache.= org/repos/asf/directory/apacheds/branches/1.0 apacheds
$ cd apacheds $ mvn -Prelease -DdryRun=3Dtrue release:prepare # Dry-run first. ...
... Make sure the change made by the release plugin is correct! <= br>...
$ mvn release:clean # Clean up the temporary files created = by the dry-run.
$ mvn -Prelease release:prepare # Copy to tags direc= tory.
$ mvn -Prelease release:perform # Upload the released artifact= s to the maven repository.
...
... Make sure the jars/poms and the= ir signature files are properly deployed to the m2-ibiblio-sync
... re= pository on people.apache.org before running the clean goal or else you can= not rollback the
... release.
...
$ mvn release:clean # Cl= ean up the temporary files.
$ mvn release:perform
{noformat}

{warning:Answering Questions= }
During the prepare goal's execution you'll be asked a number = of questions. Please pay close attention to each question instead of hitti= ng return everytime. In particular there is a question about what you want= to call the tag. If you do not specify the correct tag which should be th= e release number 1.0.2 for example, Maven will use build-1.0.2 instead with= the *build-* prefix. We don't want that so pay attention. Look here = if you have any questins regarding what release tags should be for the apac= heds subproject:
This deploys the release to a staging repository. Go to [https://repo= sitory.apache.org/index.html#stagingRepositories] and close the staging rep= ository.

http://svn.apache.org/viewvc= /directory/apacheds/tags

{warning}

These commands will bu= ild, tag, sign, and deploy apacheds artifacts and their signature files to = the repository. Check the following URLs during different stages of the pro= cess to see Maven at work:

||Stage||URL||
|after release:prepa= re| http://svn.apache.org/viewvc/directory/apacheds/tags |
|during rele= ase:perform| http://people.apache.org/repo/m2-ibiblio-rsync-repository/org/= apache/directory/server/ |

h2. Building, Signing and Deploying Ins= tallers

Now you need to build, sign and deploy the installers so t= hey are available on all Apache Mirrors. The build may change across releas= es so please keep this section updated with the latest information.
=
h3. Building Installers

Once the Maven Artifacts have been rel= eased check out the new release tag (in this example that was 1.0.2). Ther= e is a guide you can follow (link below) for preparing an enviroment to bui= ld all the installers: Izpack Jars, Windows Native Installer and the Redhat= RPM.

[Building 1.0|http://directory.apache.org/apacheds/1.0/build= ing.html]

h3. Signing and Checksuming Installers

Once you= build the installers you'll want to put them into a directory. There = you can use the [gpg-sign-all|http://mina.apache.org/developer-guide.data/g= pg-sign-all] script to generate signature (dot.asc) files and checksum file= s for SHA1 and MD5.

h3. Deploying the Installers

The inst= allers and their signature/checksum files need to be deployed to the stagin= g area used by the ASF to rsynch distributions to the ASF Mirrors. This si= mply requires you to create a new directory for the release and scp these f= iles into it. This staging area is on people.apache.org in the /www/www.ap= ache.org/dist folder. There is a 'directory' folder inside and wit= hin that there is an 'apacheds' folder. Currently inside this '= ;apacheds' folder there are two folders: one called 'stable' fo= r bug fix releases on X.0 branches and a 'unstable' folder for feat= ure releases on X.5 branches where X is the major version number. Here'= ;s what the directory layout looks like as a tree within the /www/www.apach= e.org/dist/directory folder:

h3. 5. Deploy the Site
{noformat}
.
|-- KEYS (file)
|-= - apacheds
| |-- README.txt (file)
| |-- stable
| | |--= 1.0
| | | |--1.0.0
| | | |--1.0.1
| | | |--1.0.2=
| |-- unstable
| | |--1.5
| | | |--1.5.0
$ cd target/checkout
$ mvn site-deploy
{noformat}

{info:Adding Public Key= to KEYS File}
If you have not already done so you need to add your exp= orted public key and signature to the KEYS file. All deployed artifacts si= gned by a key must have the signature and public key appended to this file.= Please make sure you back up this file before overwriting it. To add you= r key download the KEYS file and add your key to use using this command:

gpg --fingerprint --list= -sigs '<your name>' >> KEYS
&&= gpg --armor --export '<your name>' >> KEYS
This creates and deploys the site via ssh to people.apache.org/www/di= rectory.apache.org/apacheds/gen-docs.

Also make sure the permissio= ns on the KEYS file are set to allow group writes with the following comman= d:
Edit the people.apache.org/www/directory.apache.org/apacheds/gen-docs= /index.html file and add the deployed site to the list.

chmod g+w KEYS
{info} {note}
Now, you have to sign the binary packages which are in apacheds/targe= t/checkout/target.

So if you are adding a new r= elease in the 1.5 branch called 1.5.1 just create a folder 1.5.1 under the = 1.5 folder. If you're releasing on a new branch all together like say = 2.0.0 then just create the 2.0 directory under the stable folder and create= yet another folder under this new one called 2.0.0. Then you can SCP all = the signature, and checksum files including the installers themselves into = the target release folder. If you're deploying 1.0.2 for example you c= an use the following SCP command:
Use your PGP key ID (the pub key, 4096R/\[XXXXXXX\] where \[XXXXXXX\]= is the key ID)
{note}

h3. 6. Publish Source and Binary Distribution Packages
{noformat}
scp apacheds-* people.apache= .org:/www/www.apache.org/dist/directory/apacheds/stable/1.0/1.0.2
$ cd target/checkout/target
$ scp apacheds-parent-<version>= -source-release.zip.* people.apache.org:public_html/
{noformat}

Make sure all the dot.asc, d= ot.jar, dot.exe, dot.rpm, dot.md5, and dot.sha1 files are copied over and y= ou're done.
h3. Test the new version
The best way to do that is to download t= he sources, extract them, build the server and the installers, and check if= the installers are correctly working. Then check that the server is correc= tly running.

{warning:Watch Out For Group= Write Permissions}
After creating directories, deploying and/or replac= ing the KEYS file make sure group write permissions are enabled on all the = new files and folders. You might just in case want to run the following co= mmand on the top 'directory' folder to make sure you don't lock= out other developers:
h3. 8. Vote
Start a 72h vote at the dev mailing list.

chmod -R g+w /www/www.ap= ache.org/dist/directory
h3. 9. Release
If the vote succeeds Apacheds project can be relea= sed.

{warning}
Go to [https://repository.apache.org/index.html#stagingRepositories] = and release the staging repository so all artifacts are published to Maven = central.

h2. Post Release Tasks: Spre= ad the Word

After a release you want to make some announcements an= d update the links on the site to enable users and others to know about you= r new release. Follow the steps below using provided templates to easily m= ake these announcements.

h3. Adjusting the entry at projects.direc= tory.org (DOAP)

ApacheDS has an entry at [projects.directory.org|h= ttp://projects.directory.org/|projects.directory.org], published [here|http= ://projects.apache.org/projects/directory_server.html|projects.directory.or= g].

Among other things, this entry carries information about the l= atest releases of ApacheDS, and should therefore be updated after a release= . Source of the data is a file within our Subversion repository, and the on= ly thing which is necessary to do is changing it:

https://svn.apac= he.org/repos/asf/directory/apacheds/trunk/doap_apacheds.rdf

After = releasing the 1.0.2 for instance, search in the file for the release-elemen= t which describes the 1.0 branch and change version revision and creation d= ate like that:

{code:xml}
...
<release>
<V= ersion>
<name>Stable release</name>
<crea= ted>2007-05-26</created>
<revision>1.0.2</revisio= n>
</Version>
</release>
...
{code}
=
Committing the changes to the (!) trunk is the only thing necessary to = do. The technology of _projects.directory.org_ collects the file via an htt= p request periodically and builds the new information web page for ApacheDS= . Please note it takes some hours until the [web page|http://projects.apach= e.org/projects/directory_server.html|projects.directory.org] provides the u= p to date information.

h3. Add Downloads Link to Web Site
TO BE FILLED IN

h3. Preparse and Post Announcements

Use = the following guide to prepare announcements and post them to the relavent = mailing lists, forums and sites: [Making Release Announcements].
Move the distribution packages to people.apache.org/www/www.apache.or= g/dist/directory/apacheds/stable.

Full Content

<= col width=3D'24'>
3D""Outdated

Introduction

This will show you how to build and release the ApacheDS subproject. Ke= ep an eye out for warning and note sections that show version specific diff= erences in this process.

Manual Step

Some things have not yet been automated with maven and require users to = manually edit some files. Below are the steps to follow.

Update service/apacheds.sh and service/apacheds.bat

Edit the apacheds.sh/bat files in the service project directory to updat= e the revision numbers used in that file to reference non-SNAPSHOT releases= .

Release process

Since we are using Nexus for releases the release process is as follows = (see also http://www.apac= he.org/dev/publishing-maven-artifacts.html#staging-maven).

1. Test the Project<= /h3>
$ mvn release:prepare -DdryRun=3Dtrue

Replace the version by the new version. Be careful, and remove the 'apac= heds-parent-' which is proposed for the new tag. We should just use the ver= sion number.

2. Deploy a Snapsho= t

$ mvn deploy

This is useful to verify your settings in ~/.m2/settings.xml (Nexus pass= word and GPG key)

3. Prepare the Re= lease

$ mvn release:clean
$ mvn release:prepare

This creates a tag here: http://svn.apac= he.org/viewvc/directory/apacheds/tags/

4. Stage the Releas= e

$ mvn release:perform

This deploys the release to a staging repository. Go to https://repository.apache.org/index.html#stagingRepo= sitories and close the staging repository.

5. Deploy the Site
$ cd target/checkout
$ mvn site-deploy

This creates and deploys the site via ssh to people.apache.org/www/direc= tory.apache.org/apacheds/gen-docs.

Edit the people.apache.org/www/directory.apache.org/apacheds/gen-docs/in= dex.html file and add the deployed site to the list.

3D""Now, you have to sign the binary package= s which are in apacheds/target/checkout/target.

Use your PGP key ID (the pub key, 4096R/[XXXXXXX] where [XXXXXXX] is the= key ID)

6. Publish Source and Binary Distribution Packages

$ cd target/checkout/target
$ scp apacheds-parent-<version>-source-release.zip.* people.apache.or=
g:public_html/

Test the new versio= n

The best way to do that is to download the sources, extract them, build = the server and the installers, and check if the installers are correctly wo= rking. Then check that the server is correctly running.

8. Vote

Start a 72h vote at the dev mailing list.

9. Release

If the vote succeeds Apacheds project can be released.

Go to https://repository.apache.o= rg/index.html#stagingRepositories and release the staging repository so= all artifacts are published to Maven central.

Move the distribution packages to people.apache.org/www/www.apache.org/d= ist/directory/apacheds/stable.