BUILDING.txt

Notes on building/releasing Commons Parent
==========================================

These recipes should work.
Other recipes may suit other tastes!
This is the short form of "Releasing Commons Components"
https://commons.apache.org/releases/index.html

To perform the license release audit, a.k.a. "RAT check", run.

mvn apache-rat:check

Building for local repo:
-----------------------

mvn -N install

Snapshot deployment:
-------------------

mvn deploy

Preparing for release candidate:
-------------------------------
- Check for updates to plugins and dependencies.
- Ensure NOTICE has correct year.
- Ensure changes.xml is up to date (Release notes are updated during tagging)
- Ensure pom.xml header comment agrees with changes for this release
- Regenerate files:
  mvn commons-build:all -Dproject.inceptionYear=2006
  (N.B. the year is not defined in the pom to avoid propagation to components)
- Check and commit all changes

Creating release candidate tag:
------------------------------
N.B. This is done in a separate release branch so that the default branch remains a SNAPSHOT version

- Checkout default branch in clean workspace:
  git clone https://gitbox.apache.org/repos/asf/commons-parent.git commons-parent-<NN>-RC1
- cd commons-parent-<NN>-RC1
- Update the release branch:
  git checkout release
  git pull origin release
  git pull origin master
- Edit version in pom.xml to remove SNAPSHOT suffix
  mvn versions:set -DnewVersion=NN -DgenerateBackupPoms=false
  edit commons.rc.version to agree with the RC number
- Update the release notes. These are cumulative, so the new notes must be generated in a temporary file
  Generate a temporary file, for example:
  mvn changes:announcement-generate -Prelease-notes -Dchanges.version=NN -Dchanges.announcementFile=NN.tmp
  Edit the file to tidy it up, and prepend it to RELEASE-NOTES.txt
  Remove the temporary file
- Create tag the from the updated workspace:
  git commit -am "Update version numbers for Commons Parent version NN"

  git tag -s commons-parent-NN-RC1 -m "Tag Commons Parent version NN-RC1" [-u keyid] # signed tag
  OR
  git tag -a commons-parent-NN-RC1 -m "Tag Commons Parent version NN-RC1"

  git push --tags origin release

Test build of tag:
-----------------
- mvn deploy -Duser.name=ASF-login-name -Prelease -Ptest-deploy
- Check the contents of target/deploy/org/apache/commons/commons-parent/<NN>
  - should contain commons-parent-<NN>.pom, commons-parent-<NN>-site.xml and sigs/hashes
  - also -src.tar.gz, -src.zip and sigs/hashes

Deploy RC to Nexus:
------------------
- Set up passwords in settings.xml (https://wiki.apache.org/commons/UsingNexus)
- Same command as above, but omitting -Ptest-deploy profile:
- mvn package deploy -Duser.name=ASF-login-name -Prelease

Tidy and close Nexus staging area:
---------------------------------
- Login to Nexus: https://repository.apache.org/index.html
- Open "Staging Repositories", find the correct "Open" entry (check Summary tab in bottom panel)
- The message "No CLM data recorded" appears to be benign
- Open the bottom "Content" tab and navigate to the files
- Delete *.asc.md5 and *.asc.sha1 if present
- Checkout https://dist.apache.org/repos/dist/dev/commons/commons-parent
- Download the -src archives, their sigs and hashes, then delete them from Nexus.
- Commit the dist/dev/ folder

Close the staging area - Description: "Apache Commons Parent <NN> RC1"
Screen does not auto-refresh - you need to press refresh

Send round the release vote(lazy)
--------------------------------

Promote the Nexus staging area
------------------------------
Assuming the vote passes, login to Nexus and use the "Release" function
[If there was a problem identified, Drop the repo instead and start again]

Copy the RC Tag to final tag:
----------------------------
- git co release
- git pull origin release # synch with remote

- git diff commons-parent-NN-RCn # check that the workspace agrees with the tag in the vote
- git tag -s commons-parent-NN -m "Create Commons Parent NN release tag"
- git push --tags

- git checkout master
- git merge release # This should update the RN
- mvn versions:set -DnewVersion=52-SNAPSHOT -DgenerateBackupPoms=false
- Add next release tag in src/changes/changes.xml
- git commit -am "Bump to next development version"

Publish the source files to
------------------------
https://dist.apache.org/repos/dist/release/commons/commons-parent

TBA

Update site documentation
-------------------------
Please check that the site documentation is up to date 
See:
https://svn.apache.org/repos/asf/commons/cms-site/trunk/content/xdoc/commons-parent-pom.xml
This will need updating if any new features / profiles etc are added.
It does not list plugin or dependency versions.
However at the least please update the version details and URL at the start of the page.