mirror of https://github.com/apache/ant-ivy
247 lines
12 KiB
HTML
247 lines
12 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
|
|
<!--
|
|
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
|
|
|
|
http://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.
|
|
-->
|
|
<html>
|
|
<head>
|
|
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=ISO-8859-1">
|
|
<script type="text/javascript">var xookiConfig = {level: 0};</script>
|
|
<script type="text/javascript" src="xooki/xooki.js"></script>
|
|
</head>
|
|
<body>
|
|
<textarea id="xooki-source">
|
|
<h1>Building from source</h1>
|
|
To build Ivy from source it's really easy.
|
|
<h2>Requirements</h2>
|
|
All you need is
|
|
<ul>
|
|
<li>an <a href="http://subversion.tigris.org/">svn</a> client</li>
|
|
<em>to check out Ivy sources from apache svn, not required if you build from sources packaged in a release</em>
|
|
<li><a href="http://ant.apache.org/">Apache Ant</a> 1.6.0 or greater</li>
|
|
<em>We recommend either ant 1.6.5 or 1.7.0</em>
|
|
<li><a href="http://junit.org">junit</a> 3.8.2 jar in your ant lib</li>
|
|
<em> this is not required if you use ant 1.7</em>
|
|
<li>a <a href="http://java.sun.com/">jdk</a> 1.4 or greater</li>
|
|
<em>Build instructions have been successfully tested with sun jdk 1.4.2, 1.5.0 and 1.6.0</em>
|
|
</ul>
|
|
|
|
<h2>Procedure</h2>
|
|
<h3>Get the source</h3>
|
|
You can either get the sources from a [[download release]], or get them directly from svn. For instance, to get the trunk version:
|
|
<code>
|
|
svn co https://svn.apache.org/repos/asf/incubator/ivy/core/trunk ivy
|
|
</code>
|
|
<h3>Build</h3>
|
|
Go to the directory where you get the Ivy sources (you should see a file named build.xml) and run:
|
|
<code>
|
|
ant
|
|
</code>
|
|
<h3>Check the result</h3>
|
|
The ant build will download Ivy if you don't already have a proper version in your home, compile, and run tests with coverage metrics.
|
|
If everything goes well, you should see the message
|
|
<code>
|
|
BUILD SUCCESSFUL
|
|
</code>
|
|
Then you can check the test results in the build/doc/reports/test directory, the jars are in build/artifacts, and the test coverage report in build/doc/reports/coverage
|
|
<h1>Coding conventions</h1>
|
|
The Ivy code base is supposed to follow the standard java conventions:
|
|
http://java.sun.com/docs/codeconv/html/CodeConvTOC.doc.html
|
|
|
|
This is a work in progress though (see IVY-511), but patches helping migration to these conventions are welcome.
|
|
|
|
<h1>Developing with eclipse</h1>
|
|
Even though you can develop Ivy with your IDE of choice, we support eclipse development by providing ad hoc metadata.
|
|
|
|
We currently provide two options:
|
|
<h2>Eclipse alone</h2>
|
|
To develop with a simple eclipse install all you need is eclipse 3.1 or greater, with no particular plugin.
|
|
First call the following ant target in your Ivy workspace:
|
|
<code>
|
|
ant eclipse-default
|
|
</code>
|
|
This will resolve the dependencies of Ivy and produce a .classpath using the resolved jars for the build path.
|
|
Then you can use the "Import->Existing project into workspace" eclipse feature to import the Ivy project in your workspace.
|
|
<h2>Eclipse + IvyDE</h2>
|
|
You can also leverage the latest IvyDE version to be able to easily resolve the ivy dependencies from Eclipse.
|
|
To do so all you need is call the following ant target in your Ivy workspace:
|
|
<code>
|
|
ant eclipse-ivyde
|
|
</code>
|
|
or if you don't have ant installed you can simply copy the file .classpath.ivyde and rename it to .classpath
|
|
Then you can import the project using "Import->Existing project into workspace" as long as you already have latest IvyDE installed.
|
|
|
|
To install latest IvyDE version compatible with the latest Ivy used to resolve Ivy dependencies, you will need to use a snapshot build, not endorsed by the ASF, available here:
|
|
http://people.apache.org/~xavier/ivyde/snapshot/
|
|
|
|
Download the file and unzip its content in your eclipse installation directory.
|
|
|
|
<h1>Making a release</h1>
|
|
<h2>Requirements</h2>
|
|
Requirements for making a release are similar to the requirements for building from source, except that sun jdk 1.6 and ant 1.7 are required.
|
|
<h2>Procedure</h2>
|
|
<h3>1. Check the files which needs to be updated for the release.</h3>
|
|
On the trunk, check that files which require update for the release are up to date.
|
|
This includes particularly:
|
|
RELEASE_NOTES
|
|
CHANGES
|
|
README
|
|
<h3>2. Create a release branch</h3>
|
|
This will allow to work separately from other developers, in case you need any last modification.
|
|
<code>
|
|
svn copy https://svn.apache.org/repos/asf/incubator/ivy/core/trunk \
|
|
https://svn.apache.org/repos/asf/incubator/ivy/core/branches/2.0.0-alpha1 \
|
|
-m "Creating a release branch for 2.0.0-alpha1."
|
|
</code>
|
|
<h3>3. Check out the branch</h3>
|
|
<code>
|
|
svn co https://svn.apache.org/repos/asf/incubator/ivy/core/branches/2.0.0-alpha1 ivy-2.0.0-alpha1
|
|
</code>
|
|
<h3>4. Double check the files which need to be updated for the release.</h3>
|
|
Check again that files have proper revision information.
|
|
It's also time to update the documentation template files which will be used for doc generation to include the version information in the page title.
|
|
For instance in
|
|
<code>
|
|
doc/template.html
|
|
doc/printTemplate.html
|
|
</code>
|
|
replace
|
|
<code>
|
|
<title>${title} | Ivy Documentation</title>
|
|
</code>
|
|
by
|
|
<code>
|
|
<title>${title} | Ivy 2.0.0-alpha1-incubating Documentation</title>
|
|
</code>
|
|
<h3>5. Add release note page in the documentation.</h3>
|
|
Open the file doc/index.html with your favorite browser, and click on the plus button in the upper right. Choose "Release Notes" as title, and "release-notes" as page id.
|
|
|
|
Then edit the page (hit the first button at the upper right), and copy the content of the RELEASE_NOTES file in a pre section:
|
|
<code>
|
|
<pre>
|
|
Here comes the release notes...
|
|
</pre>
|
|
</code>
|
|
|
|
You can also add the announcement for the release if it's already ready. If this is an incubator version, add the usual incubator disclaimer too.
|
|
|
|
Move the page up in the TOC using the arrow button in the toolbar at the upper right, so that it's the first child page under the "Documentation" page.
|
|
|
|
The page could then look like something like that:
|
|
http://incubator.apache.org/ivy/history/2.0.0-alpha-1.html
|
|
|
|
<h3>6. Commit your changes</h3>
|
|
<code>
|
|
svn ci -m "update templates and add release notes in documentation."
|
|
</code>
|
|
<h3>7. Check that you have no pending modifications</h3>
|
|
<code>
|
|
svn status
|
|
</code>
|
|
If your working copy is clean, you can launch the release script. If it isn't, make sure to clean it properly. Sometimes you may need to call ant clean-all if you have started to work with ant builds. If you are confused about your working copy state, delete it and check it out again.
|
|
<h3>8. Launch the release script</h3>
|
|
<code>
|
|
ant -Dbuild.version=2.0.0-alpha1-incubating -Dstatus=milestone -f build-release.xml release
|
|
</code>
|
|
The status should be release only for final releases, and milestone for any other intermediate release.
|
|
If anything is wrong, fix and go back to step 4.
|
|
If the release script is successful, release artifacts will be waiting for you in the build/distrib directory.
|
|
<h3>9. Verify the release</h3>
|
|
Check that all zips can be opened correctly, and that running 'ant' after unzipping the source distribution works properly.
|
|
You can also do a smoke test with the generated ivy.jar , to see if it is able to resolve properly a basic module (for instance you can run some tutorials provided in the src/example directory in all distributions).
|
|
<h3>10. Sign and upload the artifacts</h3>
|
|
It's now time to sign the release artifacts and upload them to a location accessible by other Apache commiters.
|
|
|
|
Here is a simple way to sign the files using gnupg:
|
|
<code>
|
|
gpg --armor --output file.zip.asc --detach-sig file.zip
|
|
</code>
|
|
|
|
Here is a ruby script you can use to sign the files:
|
|
<code>
|
|
require 'find'
|
|
|
|
Find.find('build/distrib') do |f|
|
|
`gpg --armor --output #{f}.asc --detach-sig #{f}` if File.file?(f) && ['.zip', '.gz'].include?(File.extname(f))
|
|
end
|
|
</code>
|
|
Be prepared to enter your passphrase several times if you use this script, gpg will ask for your passphrase for each file to sign.
|
|
|
|
<h3>11. Cast a vote to approve the release</h3>
|
|
Cast a vote to approve the release, first on the ivy-dev mailing list, then if it is approved, on the general@incubator.apache.org mailing list
|
|
<h3>12. Tag the svn repository</h3>
|
|
Now that the release is approved, it is time to tag the svn repo
|
|
<code>
|
|
svn copy https://svn.apache.org/repos/asf/incubator/ivy/core/branches/2.0.0-alpha1 \
|
|
https://svn.apache.org/repos/asf/incubator/ivy/core/tags/2.0.0-alpha1 \
|
|
-m "Tag release 2.0.0-alpha1."
|
|
</code>
|
|
<h3>13. Upload to public repository</h3>
|
|
If the release is approved, it's now time to make it public by uploading it to the public Apache distrib repository (i.e. /www/people.apache.org/dist/incubator/ivy/[version] on people.a.o).
|
|
|
|
<h3>14. Update the web site</h3>
|
|
Add a link to the released version documentation in the web site.
|
|
|
|
To do so, you need to:
|
|
<ol>
|
|
<li>add a svn externals reference to the documentation</li>
|
|
edit the svn properties of site/history, and in the svn:externals property, add a line like this one:
|
|
<code>
|
|
2.0.0-alpha2 https://svn.apache.org/repos/asf/incubator/ivy/core/branches/2.0.0-alpha2/doc
|
|
</code>
|
|
<li>edit the toc.json file in the site component of Ivy</li>
|
|
and add something like that:
|
|
<code>
|
|
{
|
|
"title":"2.0.0-alpha2",
|
|
"importRoot":"history/2.0.0-alpha2",
|
|
"importNode":"index"
|
|
}
|
|
</code>
|
|
<li>Add a call to init-imported-version in site/build.xml</li>
|
|
In the init-imported-history target, add a task call like this one:
|
|
<code>
|
|
<init-imported-version version="2.0.0-alpha2" />
|
|
</code>
|
|
</ol>
|
|
Then launch "ant init-imported-history" in the site directory, and check the documentation now has the released version in the history, and that this documentation can be accessed with no problem with a unified TOC.
|
|
|
|
Then you can update the release notes page of the imported documentation if necessary, to include the announcement for example.
|
|
|
|
It's time to update the download image used on the home page and the download page. Use site/images/ivy-dl.xcf as a basis if you have <a href="http://www.gimp.org/">gimp</a> installed. Then you can update the home page to refer to this image, and add a news item announcing the new version. Update also the download page with the new image and update the links to the download location.
|
|
|
|
You are now ready to commit your changes (make sure to commit changes in imported locations too), and update the online site:
|
|
<code>
|
|
ant clean publish-site
|
|
</code>
|
|
|
|
<h3>15. Announce</h3>
|
|
Announce the release on the ivy-dev and ivy-user mailing lists, on the general@i.a.o list, announce@apache.org and on the user@ant.apache.org.
|
|
Announce also the release on Ivy web site by editing the doc/index.html on the trunk.
|
|
You can also announce the release on popular web sites, like freshmeat.net (xavier is the owner of the Ivy project on freshmeat), javalobby.org, theserverside.com, dzone.com, ...
|
|
<h3>16. Update this doc</h3>
|
|
If you feel like anything is missing or misleading in this release doc, update it as soon as you encounter the problem.
|
|
<h3>17. Merge your modifications back to the trunk if necessary.</h3>
|
|
Modifications on the template files do not need to be merged, but if you had troubles during your release you may want to merge your fixes back to the trunk.
|
|
<h3>18. Prepare next release</h3>
|
|
Update the file version.properties with the version of the next release so that anyone building from the trunk will obtain jar with the correct version number.
|
|
|
|
Release the version in <a href="https://issues.apache.org/jira/browse/IVY">jira</a>, and create a new unreleased version for the next planned version.</textarea>
|
|
<script type="text/javascript">xooki.postProcess();</script>
|
|
</body>
|
|
</html>
|