| :jbake-type: page |
| :jbake-status: published |
| |
| :sectnums: yes |
| |
| // to read before |
| // https://incubator.apache.org/guides/releasemanagement.html |
| // http://www.apache.org/legal/release-policy.html |
| |
| = Apache Tamaya Release Guide |
| |
| [.lead] |
| This document describes how to perform a release of Apache Tamaya |
| API&Core and Apache Tamaya Extensions during |
| its incubation. It contains a step by step description of each step, |
| so everybody in the commiters's team will be able to perform |
| the release procedure during the incubation phase. |
| Differences in the procedure between Tamaya API&Core and Tamaya |
| Extensions are mentioned. |
| |
| == Prerequisites |
| |
| This section describes the prerequisite which must be given to |
| perform the release procedure. |
| |
| ["upperroman"] |
| |
| . Subversion client, needed to upload the source distribution. |
| . Git |
| . A valid GPG key, needed to sign all artifacts created during |
| the release process. |
| |
| |
| == Performing the release |
| |
| === Tell the others you would proceed with the release procedure |
| |
| The first step is to announce on developer mailing list that |
| you plan to release a new version of Tamaya API&Core as well |
| as of the Tamaya Extensions. |
| |
| Take the mail template below, adapt it if necessary, an send it |
| to mailto:dev@tamaya.incubator.apache.org[dev@tamaya.incubator.apache.org]. |
| |
| |
| |
| .Subject of the announcement of an upcomming release |
| ---- |
| Starting with the preparation of the next release of <<project>> |
| ---- |
| |
| .Body of the announcement of an upcomming release. |
| [listing,text] |
| ---- |
| Dear all, |
| |
| If there are no objections, I'll start with the first steps for |
| the next release of <<project>> (review, documentation,...). |
| It would be great to start with the release procedure next week. |
| |
| Best regards, |
| <<your name>> |
| ---- |
| |
| Don't expect that everyone will response immediately as we all are very |
| busy. So be patient with you team members. Meanwhile you can |
| proceed with the release preparations. |
| |
| === Check if everything is ready |
| |
| The following items must be done before you can start with the |
| actual release process. |
| |
| . Check if the build chains in |
| https://builds.apache.org/view/Tamaya/[Apache's Jenkins^] |
| of the project in to be released are fine and where are |
| no problems with the build and quality of the project. |
| . Ensure that all |
| https://issues.apache.org/jira/projects/TAMAYA[JIRA^] issues |
| targeting the upcomming release are resolved. |
| If not, get in contact with the issue assignee or the reporter to |
| check |
| .. if the issue can be postponed for the next release |
| .. how long it takes to resolve it and if someone can help. |
| |
| |
| === Prepare the release notes |
| |
| * Create release notes and commit them to the `/readme/` |
| directory of the project. The file name of the release |
| notes document should be `ReleaseNotes-[version].html`. |
| |
| [TIP] |
| ==== |
| Ensure that you include only notes an the release notes |
| which affect the project you are releasing. |
| For instance a notes on an issues which affects Tamaya Extensions |
| should not be included in the release notes of Tamaya API&Core. |
| ==== |
| |
| === Preparing the vote of the PPMC on the release |
| |
| If you are sure that everything is ready for the |
| next release you can start the vote of the PPMC |
| on the proposed release. |
| |
| [IMPORTANT] |
| ==== |
| Keep in mind that preparing the release |
| really means only to prepare the release by |
| uploading it to the dev area of the |
| https://dist.apache.org[distribution |
| server of the Apache project^] and to a staging |
| repository of https://repository.apache.org[Apache's Nexus^]. |
| |
| You must not publish the artifacts created during |
| the preparation of the release until the IPMC as well |
| as the PPMC of Apache Tamaya have approved the release. |
| ==== |
| |
| Before you can present the proposed release to the |
| IPMC of the Apache Incubator, the proposed release must be |
| approved by the PPMC of the Tamaya project. |
| |
| Therefore you must run a vote on the proposed release |
| by creating a vote candidat in the Git repository of |
| the project, uploading the source distribution |
| to the dev area of the distribution server of the Apache |
| project and uploading the Maven artifacts to a staging |
| repository in Apache's Nexus. This sounds complicated |
| but it isn't that complicated if you follow the steps |
| of this guide. |
| |
| In case the vote candidate does not pass the vote of |
| the PPMC or the IPMC you can choose between |
| canceling the current attempt for the next release |
| or you try to fix the issues which hinders people to |
| vote with yes. If you have choosen the second |
| way then you have to prepare a new vote candidat. |
| |
| === Preparing the release without the Release Plugin |
| |
| [NOTE] |
| ==== |
| We tried to use the http://maven.apache.org/maven-release/maven-release-plugin/[Maven Release Plugin^] |
| to increase the level of automatisation of the release process, but |
| we were not able to get the Maven Release Plugin working as we |
| need it for our release process. Therefore we decided not to use |
| it. |
| ==== |
| |
| The first step is to create a separate branch for the release canidate. |
| The name should consist of the release version and the number of the |
| voting candidate. |
| |
| For example if you would like to run a vote for the 1.0 release of |
| Tamaya API&Core during its incubation for the second time, the usual |
| branch name would be `vote-1.0-incubating-02`. |
| |
| Follow the instructions below to create the branch for the vote |
| and to build the vote candidate. |
| |
| [code,text] |
| .Creating the vote branch and building the vote candidat |
| ---- |
| $ git checkout -b vote-[release version]-[attempt] <1> <2> |
| $ export MAVEN_OPTS="-Xmx512m -XX:MaxPermSize=200m" |
| $ mvn versions:set versions:commit -DnewVersion=[release version] -DperformRelease=true |
| $ mvn clean install -DperformRelease=true -Dgpg.keyname=[key] -Dgpg.passphrase=[passphrase] <3> <4> |
| |
| ---- |
| <1> The version number of the planed release, e.g. `0.4-incubating` |
| <2> The number of the current vote, e.g. `03` |
| <3> The id of your GPG key. |
| <4> The passphrase of you GPG key. |
| |
| Now you can check the source distribution and the Maven artifacts created |
| during the build. |
| |
| If everything is correct, deploy them to a staging repository on Apache's |
| Nexus. |
| |
| [listing,text] |
| .Deploying the vote candidate to Apache's Nexus' |
| ---- |
| $ mvn deploy |
| ---- |
| |
| // Check if these commandline parameters are needed |
| // -DperformRelease=true -Dgpg.keyname=[key] -Dgpg.passphrase=[passphrase] <1> <2> |
| |
| After deploying the artifacts you have to check the staging repository |
| created in Apache's Nexus: |
| |
| 1. Login to https://repository.apache.org/[^] and go to _Staging Repositories_. |
| 2. Check the Contents of the newly create staging repository for you release. |
| 3. Close the staging repository to let Nexus do its validations on the deployed |
| artifacts. |
| |
| IMPORTANT: Do not release the content of the stating repository right now. |
| Releasing means to publish the artifacts. This will be done |
| after a successful vote of the IPMC. |
| |
| |
| If everything is correct until now, commit your local changes, create a tag for |
| the voting candidate and push the tag and your commits to the Git |
| repository. |
| |
| |
| [listing,text] |
| .Commiting the changes done for the vote candidate |
| ---- |
| $ git add -A |
| $ git commit -m "Release Prepare: Set release version." |
| $ git tag vote-[release version]-[attempt] |
| $ git push --tags |
| ---- |
| |
| <1> The version number of the planed release, e.g. `0.4-incubating` |
| <2> The number of the current vote, e.g. `03` |
| |
| Finally open the next development version of the project. |
| |
| [listing,text] |
| .Set next development version of the project |
| ---- |
| $ mvn version:set versions:commit -DnewVersion=[development version] <1> |
| $ git add -A |
| $ git commit -m "Release Prepare: Open new development version." |
| ---- |
| <1> Next development version, e.g. `0.83-incubating-SNAPSHOT` |
| |
| After setting the new development version you have to add the source |
| distribution to the distribution repository at https://dist.apache.org/repos/dist/[^]. |
| |
| IMPORTANT: The source distribution and all required artifacts must be added |
| to the development directory of Apache's distribution server. |
| After the approvement of the release candidate by the PPMC and |
| the IPMC they will be moved to the release directory. |
| |
| |
| [listing,text] |
| .Adding all needed artifacts to distribution repository |
| ---- |
| $ svn co https://dist.apache.org/repos/dist/dev/incubator/tamaya/ |
| $ mkdir [release version]/[project] <1> |
| $ set RELEASE_HOME=`pwd`/[release version]/[project] |
| $ set PROJECT_ROOT=[repository of the project] <2> |
| $ cd $PROJECT_ROOT |
| $ cp DISCLAIMER $RELEASE_HOME |
| $ cp NOTICE $RELEASE_HOME |
| $ cp LICENCE $RELEASE_HOME |
| $ cp keys/KEYS $RELEASE_HOME |
| $ cp $PROJECT_ROOT/cp distribution/target/*{.tar.gz,.zip,.asc} $RELEASE_HOME <3> |
| $ svn add [version] |
| $ svn add [version]/[project] |
| ---- |
| <1> We store the artifacts of Tamaya API&Core and Tamaya Extensions always |
| in different subdirectories. So _project_ can be either |
| `apiandcore` or `extensions`. |
| <2> `PROJECT_ROOT` is the Git repository of the project which you want to |
| release. |
| <3> This command copies both distribution archives to `$RELEASE_HOME`. |
| |
| Additionally there must be a SHA-1 and MD5 sigature file for each distribution |
| archive and its GPG signature (`.asc`). To generate them you need programs |
| like `md5` and `shasum`. The name of these programs might vary from system to system. |
| |
| |
| [listing,text] |
| .Generating the required SHA-1 and MD5 signatures |
| ---- |
| $ cd $RELEASE_HOME |
| $ for f in $(ls *{.tar.gz,.zip,.asc}); do shasum -a 1 $f > ${f}.sha1; md5 $f > ${f}.md5; done |
| ---- |
| |
| After generating the signature files you can add and commit all files and artifacts |
| of the source distribution. |
| |
| [listing,text] |
| .Adding and commiting the source distribution |
| ---- |
| $ cd $RELEASE_HOME |
| $ svn add [project] |
| $ svn add [version] |
| $ svn commit --username [Apache ID] |
| ---- |
| |
| All commited files and artifacts should be now available via |
| https://dist.apache.org/repos/dist/dev/incubator/tamaya/[https://dist.apache.org/repos/dist/dev/incubator/tamaya/[version]/[project]^]. |
| |
| |
| == Run the vote on the release candidate |
| |
| === Run the internally |
| |
| The next step is to prepare the vote on mailto:dev@tamaya.incubator.apache.org[^]. |
| The mail must contain serveral links, e.g. a link to the source distribution |
| and a link to the tag in the Git repository. |
| |
| The following links are needed for the mail: |
| |
| 1. A link to the source distribution in the dev section of the distribution repository |
| at https://dist.apache.org/repos/dist/dev/incubator/tamaya/[^]. |
| 2. A link to the tag of the release candidate, taken from |
| https://git1-us-west.apache.org/repos/asf?p=incubator-tamaya.git;a=summary[^]. |
| 3. A link to the staging repository for the release candidate of the intended |
| relase at http://repository.apache.org/content/repositories[^]. |
| 4. A link to to the http://www.apache.org/foundation/voting.html#ReleaseVotes[rules for release votes^] |
| in the _Apache Voting Process_ document. |
| |
| Take the mail template below, insert the links, an send it |
| to mailto:dev@tamaya.incubator.apache.org[dev@tamaya.incubator.apache.org]. |
| |
| [listing,text] |
| .Subject of the vote on the release candidate |
| ---- |
| [Vote] Release of [project] [version] <1> <2> |
| ---- |
| <1> Replace _project_ by either Apache Tamaya API&Core or Apache Tamaya Extensions |
| <2> Replace _version_ by the version number of the release |
| |
| [listing,text] |
| .Body of the vote on the release candidate |
| ---- |
| [VOTE] Release of [project] [version] <1> <2> |
| |
| Hi, |
| |
| I was running the needed tasks to get the [version] release of [project] out. <1> <2> |
| The artifacts available via the Apache distribution repository [1] and |
| also via Apache's Nexus [2]. |
| |
| The tag for this release candidate is available at [3] and will be renamed |
| once the vote passed. |
| Please take a look at the artifacts and vote! |
| |
| Please note: |
| This vote is a "majority approval" with a minimum of three +1 votes (see [4]). |
| |
| ------------------------------------------------ |
| [ ] +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, |
| [name] |
| |
| [1] [link to the source distribution] <3> |
| [2] [link to the staging repository at Apache's Nexus] <4> |
| [3] [link to the tag in the Git repository] <5> |
| [4] http://www.apache.org/foundation/voting.html#ReleaseVotes |
| ---- |
| <1> Replace _project_ by the name of the project to be release, which can be |
| _Apache Tamaya API&Core_ or _Apache Tamaya Extensions_. |
| <2> Replease _version_ by the version number of the intended release. |
| <3> Insert here the link to the source distribution of the project |
| in the dev section of distribution repository |
| at https://dist.apache.org/repos/dist/dev/incubator/tamaya/[^]. |
| <4> Insert here the link to the staging repository for the release candidate |
| at http://repository.apache.org/content/repositories[^]. |
| <5> Insert here the link to the tag created for the release candidate |
| in the Git repository. |
| |
| Wait at least 72 hours before you close the result. If there is not enough attention |
| at the mailing list to vote, send a nice reminder to the list. Please keep in mind |
| that people might be simple to busy to respond on your vote. |
| |
| To close the vote count all single votes and send the result as reply to your |
| initial mail to the mailinglist by using the templates below. |
| |
| [listing,text] |
| .Subject of the mail with the result of the vote |
| ---- |
| [Result] (was: Re: [VOTE] Release of [project] [version]) <1> <2> |
| ---- |
| <1> Replace _project_ by the name of the project to be release, which can be |
| _Apache Tamaya API&Core_ or _Apache Tamaya Extensions_. |
| <2> Replease _version_ by the version number of the intended release. |
| |
| [listing,text] |
| .Body of the mail with the result of the vote |
| ---- |
| Thank you for voting! |
| |
| X binding +1 votes (PPMC): <1> |
| [list] <2> |
| |
| Y non-binding +1 votes: <3> |
| [list] <4> |
| |
| Z -1 votes: <5> |
| [list] <6> |
| ---- |
| <1> Replace _X_ by the number of positive votes by PPMC members |
| <2> Replace _list_ by the names of PPMC members with a positive vote |
| <3> Replace _Y_ by the number of non-binding positive votes by |
| non-PPMC members |
| <4> Replace _list_ by the names of non-PPMC members with a positive vote |
| <5> Replace _Z_ by the number of negative votes by PPMC members |
| <6> Replace _list_ by the names of PPMC members with a negative vote |
| |
| |
| After the vote on the PPMC has been finished and is successful, |
| repeat the voting process on the incubator mailing list. |
| |
| |
| === Let the IPMC vote on the release candidate |
| |
| During the incubation phase of Tamaya, each release must be approved |
| by the IPMC. |
| |
| The first step is to subscribe to the mailinglist |
| general@incubator.apache.org. |
| More information and how to do this can be found on |
| https://incubator.apache.org/guides/lists.html[^]. |
| |
| :x: https://lists.apache.org/list.html?dev@tamaya.apache.org |
| |
| The mail, which must be send to the list, is quite similar |
| to the one for the PPMC, but it must also contain a link |
| to the mail thread of the successful vote of the PPMC. |
| The archive of the developers mailinglist of Apache Tamaya |
| can be found at https://lists.apache.org[^]. |
| |
| The mail to the IPMC can be composed by using these both |
| templates: |
| |
| [listing,text] |
| .Subject of the vote on the release candidate |
| ---- |
| [Vote] Release of [project] [version] <1> <2> |
| ---- |
| <1> Replace _project_ by either Apache Tamaya API&Core or Apache Tamaya Extensions |
| <2> Replace _version_ by the version number of the release |
| |
| [listing,text] |
| .Body of the vote on the release candidate |
| ---- |
| [VOTE] Release of [project] [version] <1> <2> |
| |
| Dear IPMC members, |
| |
| The Apache Tamaya project was running the needed tasks to get |
| the [version] release of [project] out. <1> <2> |
| |
| The artifacts available via the Apache distribution repository [1] and |
| also via Apache's Nexus [2]. |
| |
| The tag for this release candidate is available at [3] |
| |
| The mail thread of the vote can be found at [4]. |
| |
| Please take a look at the artifacts and vote! |
| |
| Please note: |
| This vote is a "majority approval" with a minimum of three +1 votes (see [5]). |
| |
| ------------------------------------------------ |
| [ ] +1 for IPMC members who approve this release |
| [ ] +0 for IPMC members with no opinion on this release |
| [ ] -1 for IPMC members who reject this release, and why ... |
| ------------------------------------------------ |
| |
| Thanks, |
| [name] |
| |
| [1] [link to the source distribution] <3> |
| [2] [link to the staging repository at Apache's Nexus] <4> |
| [3] [link to the tag in the Git repository] <5> |
| [4] [link to the thread of the vote by the PPMC.] <6> |
| [5] http://www.apache.org/foundation/voting.html#ReleaseVotes |
| ---- |
| <1> Replace _project_ by the name of the project to be release, which can be |
| _Apache Tamaya API&Core_ or _Apache Tamaya Extensions_. |
| <2> Replease _version_ by the version number of the intended release. |
| <3> Insert here the link to the source distribution of the project |
| in the dev section of distribution repository |
| at https://dist.apache.org/repos/dist/dev/incubator/tamaya/[^]. |
| <4> Insert here the link to the staging repository for the release candidate |
| at http://repository.apache.org/content/repositories[^]. |
| <5> Insert here the link to the tag created for the release candidate |
| in the Git repository. |
| <6> Insert here the link to vote thread on Tamaya's developer mailinglist |
| for this release candidate |
| |
| Send the mail to pass:macro[general@incubator.apache.org] and let |
| the vote run for at least 72 hours. |
| |
| To close the vote count all single votes and send the result as reply |
| to your initial mail to the mailinglist by using the templates below: |
| |
| [listing,text] |
| .Subject of the mail with the result of the vote |
| ---- |
| [Result] (was: Re: [VOTE] Release of [project] [version]) <1> <2> |
| ---- |
| <1> Replace _project_ by the name of the project to be release, which can be |
| _Apache Tamaya API&Core_ or _Apache Tamaya Extensions_. |
| <2> Replease _version_ by the version number of the intended release. |
| |
| [listing,text] |
| .Body of the mail with the result of the vote |
| ---- |
| Thank you for voting! |
| |
| X binding +1 votes (PPMC): <1> |
| [list] <2> |
| |
| Y non-binding +1 votes: <3> |
| [list] <4> |
| |
| Z -1 votes: <5> |
| [list] <6> |
| ---- |
| <1> Replace _X_ by the number of positive votes by IPMC members |
| <2> Replace _list_ by the names of IPMC members with a positive vote |
| <3> Replace _Y_ by the number of non-binding positive votes by |
| non-IPMC members |
| <4> Replace _list_ by the names of non-PPMC members with a positive vote |
| <5> Replace _Z_ by the number of negative votes by IPMC members |
| <6> Replace _list_ by the names of IPMC members with a negative vote |
| |
| |
| |
| == Performing the release |
| |
| The actually release process can be started if the binding majority |
| of IPMC members have approved the release candidate. |
| |
| The first task is to create branch for the new release |
| out of the branch, created for the vote on the release candidate. |
| |
| === Tag and branch for the release |
| |
| Creating this branch requires multiple commands, as Git does not |
| allow to simply rename a remote branch. The listing below shows |
| which commands are needed to create a branch for the new release |
| |
| [listing,shell] |
| .Renaming the branch of the release candidate |
| ---- |
| $ git checkout master <1> |
| $ git branch release-[version] vote-[version]-[attempt] <2> <3> <4> |
| $ git push origin release-[version]:refs/heads/release-[version] <5> |
| $ git push origin :vote-[version]-[attempt] <6> |
| $ git branch -D vote-[version]-[attempt] <7> |
| $ git checkout -b release-[version] --track origin/release-[version] <8> |
| ---- |
| <1> Switching back to `master` |
| <2> Creating a release branch out of the vote branch |
| <3> Replace _version_ by the version number of the release |
| <4> Replace _attempt_ by the number of the successful vote attempt |
| <5> Pushing the new branch under the same name to the blessed repository |
| <6> Delete the vote branch in the blessed remote repository |
| <7> Delete the branch locally |
| <8> Checkout the new release branch and set the corresponding |
| remote branch as upstream branch |
| |
| |
| Now create a new tag for the release based on the exsting tag |
| for the release candidate and delete the tag made for |
| the release candidate: |
| |
| [listing,shell] |
| ---- |
| $ git tag release-[version] vote-[version]-[attempt] <1> <2> <3> |
| $ git tag -d vote-[version]-[attempt] <4> |
| $ git push origin :vote-[version]-[attempt] <5> |
| $ git push --tags origin <6> |
| ---- |
| <1> Creating a release tag for the release |
| <2> Replace _version_ by the version number of the release |
| <3> Replace _attempt_ by the number of the successful vote attempt |
| <4> Delete the tag made for the vote locally |
| <5> Delete tag tag mode for the vote in the blessed remote repository |
| <6> Push the new tag to the remote repository |
| |
| Now you can merge the new release branch with the prepared |
| development version to master. |
| |
| [listing,text] |
| .Merging the release branch to `master` |
| ---- |
| $ git checkout master |
| $ git merge release-[version] |
| $ git push origin master |
| ---- |
| |
| === Cleanup Jira |
| |
| Login into https://issues.apache.org/jira/browse/tamaya[Apache's Jira] and |
| close all issues in the |
| https://issues.apache.org/jira/browse/tamaya[Tamaya project^]. |
| |
| === Release the staging repository |
| |
| Login into https://repository.apache.org/[Apaches Nexus^] and |
| release to staging repository for the new release. |
| |
| Then wait some minutes and check if the artifacts have become |
| available at http://repo2.maven.org/maven2/org/apache/tamaya[^]. |
| |
| === Releasing the distribution artifacts |
| |
| The source distribution of the release candidate must now be |
| moved from the dev section of the distribution repository |
| to the release section. |
| |
| An easy way to achive this is to use the `svn mv` command |
| only with remote URLs. Before you move the distribution artifacts, |
| make sure the the directory for the version of the projects exists. |
| |
| [listing,text] |
| .Checking if the target directory exists in SVN |
| ---- |
| $ svn ls https://dist.apache.org/repos/dist/release/incubator/tamaya |
| ---- |
| |
| If the directory does not exists, create it. |
| |
| [listing,text] |
| .Creating the directory for the version of the release |
| ---- |
| $ svn mkdir https://dist.apache.org/repos/dist/release/incubator/tamaya/[versio] <1> |
| ---- |
| <1> Replace _version_ by the version number of the release. |
| |
| Now move all distribution artifacts from the dev section to the release |
| section. |
| |
| [listing,text] |
| .Moving the source distribution to the release section with SVN |
| ---- |
| $ svn mv \ |
| https://dist.apache.org/repos/dist/dev/incubator/tamaya/[version]/[project] \ <1> <2> |
| https://dist.apache.org/repos/dist/release/incubator/tamaya/[version]/[project] |
| ---- |
| <1> Replace _version_ by the version number of the release. |
| <2> Replace _project_ by the name of the project. |
| |
| To be sure that everything wents well, perform a checkout of the SVN |
| repository for the release section and check if everything is there. |
| |
| [listing,shell] |
| ---- |
| $ svn checkout https://dist.apache.org/repos/dist/release/incubator/tamaya |
| $ cd tamaya |
| $ ls -Rlah |
| ---- |
| |
| |
| == Updating the website and announcing the release |
| |
| Coordindate on the developers mailinglist the update of the website |
| for the new version and the announcement of the new version. |
