JSF Implementations
UI-Component Sets
Add-ons and Extensions
Documentation
Project Documentation
Foundation

MyFaces 2.3.x Release Checklist (Developer Info)

Wikis to follow as guides:

Checklist of tasks to perform for each release. For general information about Apache releases you may also consult Publishing Maven Artifacts.

Diary

NOTE: Make sure you have the right ssh public key set in id.apache.org page before performing the release steps.

Before performing the release you need to configure your environment if you haven't done it before.

a. Go to: Publishing Maven Artifacts
b. Go to the section SETUP YOUR DEVELOPMENT ENVIRONMENT and generate the pgp key signature. Don't forget to distribute the public key step.
Link: Generate PGP signature

NOTE: You can ignore sections GETTING YOUR PROJECT SETUP IN THE NEXUS REPOSITORY and MAVEN SPECIFIC PREPARATIONS AND PROCEDURES but reading the whole document will help you understand the release process. Also, we don't need to setup the project in nexus repository by creating a JIRA issue.

Some useful links/resources:

1. Preparing shared 4.2.9 (optional)

    NOTE: This step is optional. The current project structure does not required a "shared project" release, since it just copy the code inside the shared module in myfaces core.


  • Change shared/core/pom.xml variable to mirror updated shared copy from core and run from shared root path
    • mvn clean install -Dsynch-shared=true
    Try -DdryRun=true SUCCESS 
    mvn release:prepare -DtagBase=https://svn.apache.org/repos/asf/myfaces/shared/tags -DdryRun=true
    Release it! FAIL 
    mvn release:prepare -DtagBase=https://svn.apache.org/repos/asf/myfaces/shared/tags -Dresume=false
mvn install
mvn release:rollback
mvn release:prepare -DtagBase=https://svn.apache.org/repos/asf/myfaces/shared/tags -Dresume=false

    NOTE: Preparing the release will create the new tag in SVN, automatically checking in on your behalf. Note: If you're located in Europe then release:prepare may fail with 'Unable to tag SCM' and 'svn: No such revision X'. Wait 10 seconds and run mvn release:prepare again.

  • Stage the release for a vote

    • mvn release:perform -DtagBase=https://svn.apache.org/repos/asf/myfaces/shared/tags

2. Preparing Core 2.3.0

  • Once the environment is configured, you need to checkout the MyFaces 2.3.x development branch (currently the master branch in GitHub) https://github.com/apache/myfaces and run the following commands to prepare the MyFaces Core

    • mvn clean install
mvn install -Pgenerate-assembly -Papache-release -Dgpg.passphrase=yourphrase
# The dryRun=true don't checkin or tag anything in the scm repository, or modify the checkout. 
# Useful to check modifications to poms and scm operations.
mvn release:prepare -DprepareRelease=true -DdryRun=true
# Run again this command to prepare release 
# and commit to https://github.com/apache/myfaces/tags repository.
mvn release:prepare -DprepareRelease=true -Dresume=false

    NOTE: Preparing the release will create the new tag in SVN, automatically checking in on your behalf.

    NOTE: If you're located in Europe then release:prepare may fail with 'Unable to tag SCM' and 'svn: No such revision X'. Wait 10 seconds and run mvn release:prepare again.

    NOTE: If you see a message like "You don't have a SNAPSHOT project in the reactor projects list" it means that the workspace directory is not cleaned and Maven uses the old temporary files which contain some weird versions instead of the current SNAPSHOTs. You will have to do a mvn release:clean or start the process again from the beginning. Maven no snapshot in the project

    NOTE: If you have an issue like the one below when running the command "mvn release:prepare -DprepareRelease=true" that's because the local directory .m2/repository/org/apache/myfaces/core does not have the assembly files for the version to be released.

    [INFO] [ERROR] Failed to execute goal org.codehaus.mojo:dependency-maven-plugin:1.0:copy (copy-javadoc) on 
project myfaces-core-assembly: Unable to find artifact. Could not find artifact 
org.apache.myfaces.core:myfaces-api:jar:javadoc:2.3.1 in tomcat (http://tomcat.apache.org/dev/dist/m2-repository)
    To fix the issue, run again the following command to generate the assembly files for the version to be released 
    mvn install -Pgenerate-assembly -Papache-release -Dgpg.passphrase=yourphrase
    Finally, execute again the release prepare command: "mvn release:prepare -DprepareRelease=true -Dresume=false"

  • Verify that the new tag myfaces-core-module-2.3.0 was created: MyFaces Core Tags

    • You should be able to checkout myfaces-core-module-2.3.0 and run: mvn install

  • Stage the release for a vote

    • # Finally perform the release so artifacts are uploaded to nexus repository.
mvn release:perform -DperformRelease=true

    NOTE: This command is run from the local MyFaces 2.3.x development branch.

    NOTE: You should be able to verify that the release is now available in the Nexus Repository. For more information check step 5 of this checklist.

Some useful links/resources:

3. JIRA Release Management


  • Create 2.3.1 and 2.3.1-SNAPSHOT versions
  • Find resolved issues and close them
  • Unresolved issues moved to 2.3.1-SNAPSHOT
  • Don't forget to change to "released" the version you are trying to release in the JIRA dashboard
  • Delete any previous 2.3.x-SNAPSHOT and keep the latest one

Go to the following link perform these steps under the MyFaces Core Project: JIRA Dashboard

4. TCK


  • We can skip TCK step if there is no TCK for JSF 2.3

5. Generate assembly


  • Automatically done by maven on release:perform step and should be available in the nexus maven repository to do the final deploy.

    • Login to nexus repository using the id.apache.org account: Nexus Repository

    Now under Build Promotion go to Staging Repositories, look for orgapachemyfaces-xxxx repository. Click "close" so the artifacts can be downloaded.

    NOTE: If the artifacts have some bug when testing them you can click "drop"; if the artifacts are approved, follow the Step 8 in this wiki, so you can release them.

    More information here: Locate and examine your staging repository

    Example link: https://repository.apache.org/content/repositories/orgapachemyfaces-1130/org/apache/myfaces/core/myfaces-core-assembly/2.3.0/

    NOTE: Providing MD5 or SHA1 checksum files is now discouraged for new releases, but still allowed for past releases.



  • Otherwise you can generate them manually. Try to do it automatically javadoc and other stuff SUCCESS. It generate myfaces-core-2.3.0-bin.tar.gz and zip
    • mvn install -Pgenerate-assembly
cd assembly
mvn package
  • Create myfaces-core-2.3.0-src.tar.gz and zip manually and create .asc .sha1 for bin and src
    • openssl sha1 myfaces-core-2.3.0-src.tar.gz > myfaces-core-2.3.0-src.tar.gz.sha1
openssl sha1 myfaces-core-2.3.0-src.zip > myfaces-core-2.3.0-src.zip.sha1
gpg --armor --output myfaces-core-2.3.0-src.tar.gz.asc --detach-sig myfaces-core-2.3.0-src.tar.gz
gpg --armor --output myfaces-core-2.3.0-src.zip.asc --detach-sig myfaces-core-2.3.0-src.zip

openssl sha1 myfaces-core-2.3.0-bin.tar.gz > myfaces-core-2.3.0-bin.tar.gz.sha1
openssl sha1 myfaces-core-2.3.0-bin.zip > myfaces-core-2.3.0-bin.zip.sha1
gpg --armor --output myfaces-core-2.3.0-bin.tar.gz.asc --detach-sig myfaces-core-2.3.0-bin.tar.gz
gpg --armor --output myfaces-core-2.3.0-bin.zip.asc --detach-sig myfaces-core-2.3.0-bin.zip
  • Copy to ftp private account on people.apache.org
    • scp -p -r myfaces-core-2.3.0-bin* embreijo@people.apache.org:/home/embreijo/public_html/myfaces230binsrc/binaries
scp -p -r myfaces-core-2.3.0-src* embreijo@people.apache.org:/home/embreijo/public_html/myfaces230binsrc/sources

6. Clirr report to check binary incompatibilities success

    NOTE: I could not use the Clirr tool but I was able to use a similar tool called japicmp

    Github: https://github.com/siom79/japicmp
    Website: https://siom79.github.io/japicmp/

  • Download the jar-with-dependencies.jar archive and follow instructions to compare the two versions.

    • Example: java -jar japicmp-0.11.0-jar-with-dependencies.jar -n <v2_binary>.jar -o <v1_binary>.jar --ignore-missing-classes --html-file <dir_name>/results.html

    Report of myfaces-api-2.3.0-beta vs myfaces-api-2.3.0.jar looks good.

    NOTE: Comparison should also be done between MyFaces 2.3 API and Mojarra 2.3 API jars, that is, myfaces-api-2.3.x.jar and javax.faces-api-2.3.jar.

    Link to Mojarra 2.3 API: https://mvnrepository.com/artifact/javax.faces/javax.faces-api/2.3

7. VOTE: Send email to the MyFaces DEV - dev@myfaces.apache.org

    Subject: [VOTE] release of MyFaces Core 2.3.0

Hi,

I was running the needed tasks to get the 2.3.0 release of Apache
MyFaces core out.


Please note that this vote concerns all of the following parts:
   1. Maven artifact group "org.apache.myfaces.core" v2.3.0  [1]

The artifacts were deployed on nexus repo [1] for binary and source packages.

The release notes could be found at [4].

Also the japicmp tool (similar to clirr) does not show binary incompatibilities with myfaces-api.

Please take a look at the "2.3.0" artifacts and vote! (see [3])

Please note: This vote is "majority approval" with a minimum of three +1 votes (see [2]).

------------------------------------------------
[ ] +1 for community members who have reviewed the bits
[ ] +0
[ ] -1 for fatal flaws that should cause these bits not to be released, and why..............
------------------------------------------------

Thanks,
Eduardo M. Breijo

[1] https://repository.apache.org/content/repositories/orgapachemyfaces-1130/org/apache/myfaces/core/
[2] http://www.apache.org/foundation/voting.html#ReleaseVotes
[3] https://repository.apache.org/content/repositories/orgapachemyfaces-1130/org/apache/myfaces/core/myfaces-core-assembly/
[4] https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=10600&version=12339569

    NOTE: To generate the ReleaseNote you need to go to the JIRA dashboard. Then go to MyFaces Core project. Finally go to the version to be released (example 2.3.0) and click "Release Notes" button.

8. Vote closed, starting distribution

  • Now that the voting is closed, go the Nexus Repository and find the myfaces 2.3.0 repo (example: orgapachemyfaces-1130) and click the release button (the automatically drop after release checkbox is checked by default, leave it checked). More information here: Close and drop or release your staging repository

    • Some useful links/resources:

  • You can use the MyFaces Release Artifacts script to download the assembly files from Released MyFaces Core Assembly and upload them to svn dist repo: MyFaces Distribution Repository

    • To execute the script run: "./release-artifacts.sh <version> <svn_username>"

    Example: ./release-artifacts.sh 2.3.0 yourusername

    NOTE: Depending on the operating system, you might need to change the following line in the script to use "f" instead of "file" if you get this issue: "find: Arguments to -type should contain only one letter" 

    # Note that "f" is being used instead of "file"
for file in $(find . -type f -name "${PATTERN}" -exec basename \{\} \; ) ; do


  • Otherwise, use an svn client and add the release artifacts to the svn dist repo: MyFaces Distribution Repository
    • myfaces-core-assembly-${VERSION}-bin.* should go under the binaries directory
    • myfaces-core-assembly-${VERSION}-src.* should go under the source directory

    NOTE: Providing MD5 or SHA1 checksum files is now discouraged for new releases, but still allowed for past releases. From now on, use the SHA512 checksum files generated by The MyFaces Release Artifacts script.


  • Files can also be found in the following link once they are added to the svn repo: MyFaces Distribution Server
  • Make sure to remove the previous release from both binaries and source directories of the svn dist repo after adding the new release: MyFaces Distribution Repository
    • Command: svn delete URL... -m "commit message"
    • Example: svn delete https://dist.apache.org/repos/dist/release/myfaces/source/myfaces-core-assembly-2.3.0-src.tar.gz -m "delete 2.3.0 source"
    • Note that you need to delete the previous release files one by one from both binaries and source directories.
  • Add the release version and date to the Apache Committee Report Helper: Add Release

9. Site deploy for shared and core (mvn site:site and mvn site:deploy)

  • The site you can see here: https://myfaces.apache.org/ is synced by some automatic job from this SVN repo: https://svn.apache.org/repos/asf/myfaces/site/publish/

  • So, you need to

      • 1. checkout the relevant parts from that publish URL
      2. building the site (mvn site:site) as in the above step
      3. syncing this site (from 2.) locally to the checkout (from 1.) using "mvn site:stage"
      4. commit it

  • Checkout the main site from SVN repo https://svn.apache.org/repos/asf/myfaces/site/trunk/

    • Modify and commit the changes 
    src/site/apt/download.apt
src/site/apt/index.apt
src/site/resources/doap_MyFaces.rdf (if necessary)
src/site/site.xml (if necessary)
    Execute 
    mvn site:site # this will generate the site under the target directory
    After the new files have been generated, copy and paste the new generated files into site publish directory and commit them using SVN. The main site SVN repo: https://svn.apache.org/repos/asf/myfaces/site/publish/

    NOTE: You need to checkout the site publish SVN repository first in order to perform the copy and paste of the generated files to then commit them.

  • Checkout the MyFaces 2.3.x tag to be released from https://github.com/apache/myfaces/tags

    • NOTE: The MyFaces 2.3.x tag is what you want to use to generate the rest of the website if no changes are needed in the development branch (files below).
    NOTE: If changes are needed in the files below, you have to do modify and commit these changes to the MyFaces 2.3.x development branch (currently the 2.3.x branch in GitHub) in https://github.com/apache/myfaces repository to keep the dev repo up to date. Also consider commiting the files (changes) in the master branch (MyFaces 3.0.x). 
    api/src/site/apt/index.apt (if necessary)
impl/src/site/apt/index.apt (if necessary)
parent/src/site/apt/index.apt (if necessary)
parent/src/site/site.xml (if necessary)
parent/src/site/xdoc/release-checklist.xml (if necessary)
parent/src/site/resources/scripts/release-artifacts.sh (if necessary)
    Execute on the MyFaces 2.3.x tag that you checked out if no changes were needed, otherwise execute in the updated 2.3.x development branch. 
    mvn site:site # this will generate the site under the target directory
    Commit the new generated files under core23 site SVN repo: https://svn.apache.org/repos/asf/myfaces/site/publish/core23

    NOTE: The directories to commit from the generated MyFaces 2.3.x project (either from the MyFaces 2.3.x tag or the MyFaces 2.3.x development branch, depending on what you are using to generate the site) into the MyFaces site publish SVN repository are listed below. One way to achieve this is just copying and pasting the directories into the publish core23 directory, then with SVN you can see all the modifications and commit them. Please keep in mind that you are committing a lot of files so it will take some time depending on your internet speed.

    parent/target/site --> core23
api/target/site --> core23/myfaces-api
bundle/target/site --> core23/myfaces-bundle
impl/target/site --> core23/myfaces-impl
impl-test/target/site --> core23/myfaces-impl-test
shared/target/site --> core23/myfaces-impl-shared
shared-public/target/site --> core23/myfaces-impl-shared-public
target/site --> core23/module

  • Finally generate the tld docs and webconfig.html file (if necessary)

    • These docs are: tagdoc, tlddoc, tlddoc-facelets directories, tagdoc.html, webconfig.html

    Run on the MyFaces 2.3.x tag that you checked out if no changes were needed, otherwise execute in the updated 2.3.x development branch.

    mvn -Pgenerate-site -Pgenerate-tlddoc site
    Copy and paste the generated files into the publish core23/myfaces-impl directory and commit them. It should be under the following SVN repo https://svn.apache.org/repos/asf/myfaces/site/publish/core23/myfaces-impl

10. Announce

  • Sent announcement mail

    • To: announce@apache.org, announce@myfaces.apache.org
    Cc: dev@myfaces.apache.org, users@myfaces.apache.org

  • Sent announcement to jcp-open@apache.org (Necessary for TCK certified releases)

    • Subject: [ANNOUNCE] MyFaces Core v2.3.0 Release

The Apache MyFaces team is pleased to announce the release of MyFaces Core 2.3.0.

MyFaces Core is a JavaServer(tm) Faces 2.3 implementation as specified by JSR-372.

JavaServer Faces (JSF) is a Java specification for building component-based user interfaces for web applications.

MyFaces Core 2.3.0 is available in both binary and source distributions.

    * http://myfaces.apache.org/download.html

MyFaces Core is also available in the central Maven repository under Group ID "org.apache.myfaces.core".

Release Notes - MyFaces Core - Version 2.3.0 can be found in the following link: 
https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=10600&version=12339569

Regards,
Eduardo M. Breijo

NOTE: If you use your personal email to send the announcement to announce@apache.org and announce@myfaces.apache.org it will bounce back and it will not be delivered. To get around this, please login into the apache webclient Announce @ Apache and Announce @ MyFaces Apache. You need to use your apache id credentials and from each list, start a new discussion in the top right corner.