http://git-wip-us.apache.org/repos/asf/sling-site/blob/53c84cf9/content/documentation/development/release-management.md ---------------------------------------------------------------------- diff --git a/content/documentation/development/release-management.md b/content/documentation/development/release-management.md index 29c2b65..e6aef56 100644 --- a/content/documentation/development/release-management.md +++ b/content/documentation/development/release-management.md @@ -1,7 +1,10 @@ -title=Release Management -type=page +title=TODO title for release-management.md +date=1900-01-01 +type=post +tags=blog status=published ~~~~~~ +Title: Release Management Sling releases (and SNAPSHOTS) are deployed to the [Nexus repository](http://repository.apache.org) instead of the traditional deployment via the Maven 2 mirrors source on `people.apache.org`. This makes the release process much leaner and simpler. In addtion we can benefit from the Apache Parent POM 6, which has most of the release profile setup built-in. @@ -20,31 +23,31 @@ Most of the hard work of preparing and deploying the release is done by Maven. *Note*: Listing the Apache servers in the `settings.xml` file also requires adding the password to that file. Starting with Maven 2.1 this password may be encrypted and needs not be give in plaintext. Please refer to [Password Encryption](http://maven.apache.org/guides/mini/guide-encryption.html) for more information. -In the past we staged release candidates on our local machines using a semi-manual process. Now that we inherit from the Apache parent POM version 6, a repository manager will automatically handle staging for you. This means you now only need to specify your GPG passphrase in the release profile of your `${user.home}/.m2/settings.xml`: +In the past we staged release candidates on our local machines using a semi-manual process. Now that we inherit from the Apache parent POM version 6, a repository manager will automatically handle staging for you. This means you now only need to specify your GPG passphrase in the release profile of your `$\{user.home\}/.m2/settings.xml`: -<settings> -... -<profiles> -<profile> -<id>apache-release</id> -<properties> -<gpg.passphrase> <!-- YOUR KEY PASSPHRASE --> </gpg.passphrase> -</properties> -</profile> -</profiles> -... -</settings> + <settings> + ... + <profiles> + <profile> + <id>apache-release</id> + <properties> + <gpg.passphrase> <!-- YOUR KEY PASSPHRASE --> </gpg.passphrase> + </properties> + </profile> + </profiles> + ... + </settings> Everything else has been configured in the latest Sling Parent POM: -<parent> -<groupId>org.apache.sling</groupId> -<artifactId>sling</artifactId> -<version>6</version> -</parent> + <parent> + <groupId>org.apache.sling</groupId> + <artifactId>sling</artifactId> + <version>6</version> + </parent> @@ -56,88 +59,88 @@ First prepare your POMs for release: 1. Make sure there are no snapshots in the POMs to be released. In case you rely on a release version which is not yet promoted, you have to temporarily switch that dependency version to the release version. This might break the Jenkins CI build though, as the staged version is not yet visible to Jenkins, so revert this change after you have staged the release candidate. 1. Check that your POMs will not lose content when they are rewritten during the release process -$ mvn release:prepare -DdryRun=true + $ mvn release:prepare -DdryRun=true -Compare the original `pom.xml` with the one called `pom.xml.tag` to see if the license or any other info has been removed. This has been known to happen if the starting `<project>` tag is not on a single line. The only things that should be different between these files are the `<version>` and `<scm>` elements. If there are any other changes, you must fix the original `pom.xml` file and commit before proceeding with the release. + Compare the original `pom.xml` with the one called `pom.xml.tag` to see if the license or any other info has been removed. This has been known to happen if the starting `<project>` tag is not on a single line. The only things that should be different between these files are the `<version>` and `<scm>` elements. If there are any other changes, you must fix the original `pom.xml` file and commit before proceeding with the release. 1. Publish a snapshot -$ mvn deploy -... -[INFO] [deploy:deploy] -[INFO] Retrieving previous build number from apache.snapshots.https -... + $ mvn deploy + ... + [INFO] [deploy:deploy] + [INFO] Retrieving previous build number from apache.snapshots.https + ... -* If you experience an error during deployment like a HTTP 401 check your settings for the required server entries as outlined in the *Prerequisites* -* Make sure the generated artifacts respect the Apache release [rules](http://www.apache.org/dev/release.html): NOTICE and LICENSE files should be present in the META-INF directory within the jar. For -sources artifacts, be sure that your POM does not use the maven-source-plugin:2.0.3 which is broken. The recommended version at this time is 2.0.4 -* You should verify the deployment under the [snapshot](https://repository.apache.org/content/groups/snapshots/org/apache/sling) repository on Apache + * If you experience an error during deployment like a HTTP 401 check your settings for the required server entries as outlined in the *Prerequisites* + * Make sure the generated artifacts respect the Apache release [rules](http://www.apache.org/dev/release.html): NOTICE and LICENSE files should be present in the META-INF directory within the jar. For \-sources artifacts, be sure that your POM does not use the maven-source-plugin:2.0.3 which is broken. The recommended version at this time is 2.0.4 + * You should verify the deployment under the [snapshot](https://repository.apache.org/content/groups/snapshots/org/apache/sling) repository on Apache 1. Prepare the release -$ mvn release:clean -$ mvn release:prepare + $ mvn release:clean + $ mvn release:prepare -* Preparing the release will create the new tag in SVN, automatically checking in on your behalf -* If you get a build failure because of an SVN commit problem (namely *The specified baseline is not the latest baseline, so it may not be checked out.*), just repeat the `mvn release:prepare` command until SVN is happy. This is based on a known timing issue when using the European SVN mirror. + * Preparing the release will create the new tag in SVN, automatically checking in on your behalf + * If you get a build failure because of an SVN commit problem (namely *The specified baseline is not the latest baseline, so it may not be checked out.*), just repeat the `mvn release:prepare` command until SVN is happy. This is based on a known timing issue when using the European SVN mirror. 1. Stage the release for a vote -$ mvn release:perform + $ mvn release:perform -* The release will automatically be inserted into a temporary staging repository for you, see the Nexus [staging documentation](http://www.sonatype.com/books/nexus-book/reference/staging.html) for full details -* You can continue to use `mvn release:prepare` and `mvn release:perform` on other sub-projects as necessary on the same machine and they will be combined in the same staging repository - this is useful when making a release of multiple Sling modules. + * The release will automatically be inserted into a temporary staging repository for you, see the Nexus [staging documentation](http://www.sonatype.com/books/nexus-book/reference/staging.html) for full details + * You can continue to use `mvn release:prepare` and `mvn release:perform` on other sub-projects as necessary on the same machine and they will be combined in the same staging repository - this is useful when making a release of multiple Sling modules. 1. Close the staging repository: -* Login to [https://repository.apache.org](https://repository.apache.org) using your Apache SVN credentials. Click on *Staging* on the left. Then click on *org.apache.sling* in the list of repositories. In the panel below you should see an open repository that is linked to your username and IP. Right click on this repository and select *Close*. This will close the repository from future deployments and make it available for others to view. If you are staging multiple releases together, skip this step until you have staged everything + * Login to [https://repository.apache.org](https://repository.apache.org) using your Apache SVN credentials. Click on *Staging* on the left. Then click on *org.apache.sling* in the list of repositories. In the panel below you should see an open repository that is linked to your username and IP. Right click on this repository and select *Close*. This will close the repository from future deployments and make it available for others to view. If you are staging multiple releases together, skip this step until you have staged everything 1. Verify the staged artifacts -* If you click on your repository, a tree view will appear below. You can then browse the contents to ensure the artifacts are as you expect them. Pay particular attention to the existence of *.asc (signature) files. If you don't like the content of the repository, right click your repository and choose *Drop*. You can then rollback your release (see *Canceling the Release*) and repeat the process -* Note the staging repository URL, especially the number at the end of the URL. You will need this in your vote email + * If you click on your repository, a tree view will appear below. You can then browse the contents to ensure the artifacts are as you expect them. Pay particular attention to the existence of \*.asc (signature) files. If you don't like the content of the repository, right click your repository and choose *Drop*. You can then rollback your release (see *Canceling the Release*) and repeat the process + * Note the staging repository URL, especially the number at the end of the URL. You will need this in your vote email ## Starting the Vote Propose a vote on the dev list with the closed issues, the issues left, and the staging repository - for example: -To: "Sling Developers List" <d...@sling.apache.org> -Subject: [VOTE] Release Apache Sling ABC version X.Y.Z - -Hi, - -We solved N issues in this release: -https://issues.apache.org/jira/browse/SLING/fixforversion/... - -There are still some outstanding issues: -https://issues.apache.org/jira/browse/SLING/component/... - -Staging repository: -https://repository.apache.org/content/repositories/orgapachesling-[YOUR REPOSITORY ID]/ - -You can use this UNIX script to download the release and verify the signatures: -http://svn.apache.org/repos/asf/sling/trunk/check_staged_release.sh - -Usage: -sh check_staged_release.sh [YOUR REPOSITORY ID] /tmp/sling-staging - -Please vote to approve this release: - -[ ] +1 Approve the release -[ ] 0 Don't care -[ ] -1 Don't release, because ... - -This majority vote is open for at least 72 hours. + To: "Sling Developers List" <d...@sling.apache.org> + Subject: [VOTE] Release Apache Sling ABC version X.Y.Z + + Hi, + + We solved N issues in this release: + https://issues.apache.org/jira/browse/SLING/fixforversion/... + + There are still some outstanding issues: + https://issues.apache.org/jira/browse/SLING/component/... + + Staging repository: + https://repository.apache.org/content/repositories/orgapachesling-[YOUR REPOSITORY ID]/ + + You can use this UNIX script to download the release and verify the signatures: + http://svn.apache.org/repos/asf/sling/trunk/check_staged_release.sh + + Usage: + sh check_staged_release.sh [YOUR REPOSITORY ID] /tmp/sling-staging + + Please vote to approve this release: + + [ ] +1 Approve the release + [ ] 0 Don't care + [ ] -1 Don't release, because ... + + This majority vote is open for at least 72 hours. ## Wait for the Results From [Votes on Package Releases](http://www.apache.org/foundation/voting.html): -> Votes on whether a package is ready to be released follow a format similar to majority -> approval -- except that the decision is officially determined solely by whether at least -> three +1 votes were registered. Releases may not be vetoed. Generally the community -> will table the vote to release if anyone identifies serious problems, but in most cases -> the ultimate decision, once three or more positive votes have been garnered, lies with -> the individual serving as release manager. The specifics of the process may vary from -> project to project, but the 'minimum of three +1 votes' rule is universal. +> Votes on whether a package is ready to be released follow a format similar to majority +> approval -- except that the decision is officially determined solely by whether at least +> three \+1 votes were registered. Releases may not be vetoed. Generally the community +> will table the vote to release if anyone identifies serious problems, but in most cases +> the ultimate decision, once three or more positive votes have been garnered, lies with +> the individual serving as release manager. The specifics of the process may vary from +> project to project, but the 'minimum of three \+1 votes' rule is universal. The list of binding voters is available on the [Project Team](/project-information/project-team.html) page. @@ -146,21 +149,21 @@ If the vote is successful, post the result to the dev list - for example: -To: "Sling Developers List" <d...@sling.apache.org> -Subject: [RESULT] [VOTE] Release Apache Sling ABC version X.Y.Z - -Hi, - -The vote has passed with the following result : - -+1 (binding): <<list of names>> -+1 (non binding): <<list of names>> - -I will copy this release to the Sling dist directory and -promote the artifacts to the central Maven repository. + To: "Sling Developers List" <d...@sling.apache.org> + Subject: [RESULT] [VOTE] Release Apache Sling ABC version X.Y.Z + + Hi, + + The vote has passed with the following result : + + +1 (binding): <<list of names>> + +1 (non binding): <<list of names>> + + I will copy this release to the Sling dist directory and + promote the artifacts to the central Maven repository. -Be sure to include all votes in the list and indicate which votes were binding. Consider -1 votes very carefully. While there is technically no veto on release votes, there may be reasons for people to vote -1. So sometimes it may be better to cancel a release when someone, especially a member of the PMC, votes -1. +Be sure to include all votes in the list and indicate which votes were binding. Consider \-1 votes very carefully. While there is technically no veto on release votes, there may be reasons for people to vote \-1. So sometimes it may be better to cancel a release when someone, especially a member of the PMC, votes \-1. If the vote is unsuccessful, you need to fix the issues and restart the process - see *Canceling the Release*. Note that any changes to the artifacts under vote require a restart of the process, no matter how trivial. When restarting a vote version numbers must not be reused, since binaries might have already been copied around. @@ -175,9 +178,9 @@ If the vote fails, or you decide to redo the release: 1. Remove the release tag from Subversion (`svn del ...`) 1. Login to [https://repository.apache.org](https://repository.apache.org) using your Apache SVN credentials. Click on *Staging* on the left. Then click on *org.apache.sling* in the list of repositories. In the panel below you should see a closed repository that is linked to your username and IP (if it's not yet closed you need to right click and select *Close*). Right click on this repository and select *Drop*. 1. Remove the old version from Jira -1. Create a new version in Jira with a version number following the one of the cancelled release -1. Move all issues with the fix version set to the cancelled release to the next version -1. Delete the old version from Jira + 1. Create a new version in Jira with a version number following the one of the cancelled release + 1. Move all issues with the fix version set to the cancelled release to the next version + 1. Delete the old version from Jira 1. Commit any fixes you need to make and start a vote for a new release. ## Promoting the Release @@ -186,12 +189,12 @@ If the vote passes: 1. Push the release to [https://dist.apache.org/repos/dist/release/sling/](https://dist.apache.org/repos/dist/release/sling/). This is only possible for PMC members (for a reasoning look at [http://www.apache.org/dev/release.html#upload-ci](http://www.apache.org/dev/release.html#upload-ci)). If you are not a PMC member, please ask one to do the upload for you. -1. Commit the released artifacts to [https://dist.apache.org/repos/dist/release/sling/](https://dist.apache.org/repos/dist/release/sling/) which is replicated to [http://www.apache.org/dist/sling/](http://www.apache.org/dist/sling/) quickly via svnpubsub. Hint: use svn import to avoid having to checkout the whole folder first. The easiest to do this is to get the released artifact using the check script (check_staged_release.sh) and then simply copy the artifacts from the downloaded folder to your local checkout folder. Make sure to not add the checksum files for the signature file *.asc.*). -* Make sure to *not* change the end-of-line encoding of the .pom when uploaded via svn import! Eg when a windows style eol encoded file is uploaded with the setting '*.pom = svn:eol-style=native' this would later fail the signature checks! -1. Delete the old release artifacts from that same dist.apache.org svn folder (the dist directory is archived) + 1. Commit the released artifacts to [https://dist.apache.org/repos/dist/release/sling/](https://dist.apache.org/repos/dist/release/sling/) which is replicated to [http://www.apache.org/dist/sling/](http://www.apache.org/dist/sling/) quickly via svnpubsub. Hint: use svn import to avoid having to checkout the whole folder first. The easiest to do this is to get the released artifact using the check script (check_staged_release.sh) and then simply copy the artifacts from the downloaded folder to your local checkout folder. Make sure to not add the checksum files for the signature file \*.asc.\*). + * Make sure to *not* change the end-of-line encoding of the .pom when uploaded via svn import! Eg when a windows style eol encoded file is uploaded with the setting '*.pom = svn:eol-style=native' this would later fail the signature checks! + 1. Delete the old release artifacts from that same dist.apache.org svn folder (the dist directory is archived) 1. Push the release to Maven Central -1. Login to [https://repository.apache.org](https://repository.apache.org) with your Apache SVN credentials. Click on *Staging*. Find your closed staging repository and select it by checking the select box. Select the *Releases* repository from the drop-down list and click *Release* from the menu above. -1. Once the release is promoted click on *Repositories*, select the *Releases* repository and validate that your artifacts are all there. + 1. Login to [https://repository.apache.org](https://repository.apache.org) with your Apache SVN credentials. Click on *Staging*. Find your closed staging repository and select it by checking the select box. Select the *Releases* repository from the drop-down list and click *Release* from the menu above. + 1. Once the release is promoted click on *Repositories*, select the *Releases* repository and validate that your artifacts are all there. 1. Update the news section on the website at [news](/news.html). 1. Update the download page on the website at [downloads](/downloads.cgi) to point to the new release. @@ -213,35 +216,35 @@ Close all issues associated with the released version. We usually do such announcements only for "important" releases, as opposed to small individual module releases which are just announced on our [news](/news.html) page. -To: "Sling Developers List" <d...@sling.apache.org>, "Apache Announcements" <annou...@apache.org> -Subject: [ANN] Apache Sling ABC version X.Y.Z Released - -The Apache Sling team is pleased to announce the release of Apache Sling ABC version X.Y.Z - -Apache Sling is a web framework that uses a Java Content Repository, such as Apache Jackrabbit, to store and manage content. Sling applications use either scripts or Java servlets, selected based on simple name conventions, to process HTTP requests in a RESTful way. - -<<insert short description of the sub-project>> - -http://sling.apache.org/site/apache-sling-ABC.html - -This release is available from http://sling.apache.org/site/downloads.cgi - -Building from verified sources is recommended, but convenience binaries are -also available via Maven: - -<dependency> -<groupId>org.apache.sling</groupId> -<artifactId>org.apache.sling.ABC</artifactId> -<version>X.Y.Z</version> -</dependency> - -Release Notes: - -<<insert release notes in text format from JIRA>> - -Enjoy! - --The Sling team + To: "Sling Developers List" <d...@sling.apache.org>, "Apache Announcements" <annou...@apache.org> + Subject: [ANN] Apache Sling ABC version X.Y.Z Released + + The Apache Sling team is pleased to announce the release of Apache Sling ABC version X.Y.Z + + Apache Sling is a web framework that uses a Java Content Repository, such as Apache Jackrabbit, to store and manage content. Sling applications use either scripts or Java servlets, selected based on simple name conventions, to process HTTP requests in a RESTful way. + + <<insert short description of the sub-project>> + + http://sling.apache.org/site/apache-sling-ABC.html + + This release is available from http://sling.apache.org/site/downloads.cgi + + Building from verified sources is recommended, but convenience binaries are + also available via Maven: + + <dependency> + <groupId>org.apache.sling</groupId> + <artifactId>org.apache.sling.ABC</artifactId> + <version>X.Y.Z</version> + </dependency> + + Release Notes: + + <<insert release notes in text format from JIRA>> + + Enjoy! + + -The Sling team *Important*: Add the release to the Software section of the next board report below [Reports](https://cwiki.apache.org/confluence/display/SLING/Reports). @@ -256,57 +259,57 @@ While the Sling IDE tooling is built using Maven, the toolchain that it is based 1. set the fix version as released: `mvn tycho-versions:set-version -DnewVersion=1.0.2` 1. update the version of the source-bundle project to 1.0.2 -1. commit the change to svn +1. commit the change to svn 1. manually tag in svn using `svn copy https://svn.apache.org/repos/asf/sling/trunk/tooling/ide https://svn.apache.org/repos/asf/sling/tags/sling-ide-tooling-1.0.2` 1. update to next version: `mvn tycho-versions:set-version -DnewVersion=1.0.3-SNAPSHOT` and also update the version of the source-bundle project -1. commit the change to svn +1. commit the change to svn 1. Checkout the version from the tag and proceed with the build from there `https://svn.apache.org/repos/asf/sling/tags/sling-ide-tooling-1.0.2` -1. build the project with p2/gpg signing enabled: `mvn clean package -Psign` -1. build the source bundle from the source-bundle directory: `mvn clean package` -1. copy the following artifacts to https://dist.apache.org/repos/dist/dev/sling/ide-tooling-1.0.2 -1. source bundle ( org.apache.sling.ide.source-bundle-1.0.2.zip ) -1. zipped p2 repository ( org.apache.sling.ide.p2update-1.0.2.zip ) +1. build the project with p2/gpg signing enabled: `mvn clean package -Psign` +1. build the source bundle from the source-bundle directory: `mvn clean package` +1. copy the following artifacts to https://dist.apache.org/repos/dist/dev/sling/ide-tooling-1.0.2 + 1. source bundle ( org.apache.sling.ide.source-bundle-1.0.2.zip ) + 1. zipped p2 repository ( org.apache.sling.ide.p2update-1.0.2.zip ) 1. ensure the artifacts are checksummed and gpg-signed by using the `tooling/ide/sign.sh` script -1. call the vote +1. call the vote The format of the release vote should be -To: "Sling Developers List" <d...@sling.apache.org> -Subject: [VOTE] Release Apache Sling IDE Tooling version X.Y.Z - -Hi, + To: "Sling Developers List" <d...@sling.apache.org> + Subject: [VOTE] Release Apache Sling IDE Tooling version X.Y.Z -We solved N issues in this release: -https://issues.apache.org/jira/browse/SLING/fixforversion/ + Hi, -There are still some outstanding issues: -https://issues.apache.org/jira/browse/SLING/component/12320908 + We solved N issues in this release: + https://issues.apache.org/jira/browse/SLING/fixforversion/ -The release candidate has been uploaded at -https://dist.apache.org/repos/dist/dev/sling, The release artifact is -the source bundle - org.apache.sling.ide.source-bundle-X.Y.Z.zip - -which can be used to build the project using + There are still some outstanding issues: + https://issues.apache.org/jira/browse/SLING/component/12320908 -mvn clean package + The release candidate has been uploaded at + https://dist.apache.org/repos/dist/dev/sling, The release artifact is + the source bundle - org.apache.sling.ide.source-bundle-X.Y.Z.zip - + which can be used to build the project using -The resulting binaries can be installed into an Eclipse instance from -the update site which is found at p2update/target/repository after -building the project. + mvn clean package -You can use this UNIX script to download the release and verify the signatures: -http://svn.apache.org/repos/asf/sling/trunk/tooling/ide/check_staged_release.sh + The resulting binaries can be installed into an Eclipse instance from + the update site which is found at p2update/target/repository after + building the project. -Usage: -sh check_staged_release.sh X.Y.Z /tmp/sling-staging + You can use this UNIX script to download the release and verify the signatures: + http://svn.apache.org/repos/asf/sling/trunk/tooling/ide/check_staged_release.sh -Please vote to approve this release: + Usage: + sh check_staged_release.sh X.Y.Z /tmp/sling-staging -[ ] +1 Approve the release -[ ] 0 Don't care -[ ] -1 Don't release, because ... + Please vote to approve this release: -This majority vote is open for at least 72 hours + [ ] +1 Approve the release + [ ] 0 Don't care + [ ] -1 Don't release, because ... + This majority vote is open for at least 72 hours + Once the release has passed, the following must be done: @@ -315,8 +318,8 @@ Once the release has passed, the following must be done: 1. upload p2update.zip* to https://dist.apache.org/repos/dist/release/sling/ 1. upload unzipped update site to https://dist.apache.org/repos/dist/release/sling/eclipse/1.0.2 1. upload the source bundle to https://dist.apache.org/repos/dist/release/sling/eclipse/1.0.2 -1. create GPG signatures and checksums for all uploaded jars using the `tooling/ide/sign.sh` script -1. update https://dist.apache.org/repos/dist/release/sling/eclipse/composite{Content,Artifacts}.xml to point version 1.0.2 + 1. create GPG signatures and checksums for all uploaded jars using the `tooling/ide/sign.sh` script +1. update https://dist.apache.org/repos/dist/release/sling/eclipse/composite\{Content,Artifacts}.xml to point version 1.0.2 1. archive the old artifact versions but leave pointers to archive.apache.org, using compositeArtifacts.xml/compositeContent.xml , with a single child entry pointing to https://archive.apache.org/dist/sling/eclipse/1.0.0/ 1. remove the staged artifacts from https://dist.apache.org/repos/dist/dev/sling/ide-tooling-1.0.2 1. update the news page and the download pages @@ -324,104 +327,113 @@ Once the release has passed, the following must be done: ## Appendix A: Create and Add your key to [https://people.apache.org/keys/group/sling.asc](https://people.apache.org/keys/group/sling.asc) -Considering that you are using a *nix system with a working OpenSSH, GnuPG, and bash you can create and add your own key with the following commands: +Considering that you are using a \*nix system with a working OpenSSH, GnuPG, and bash you can create and add your own key with the following commands: 1. Create a public/private pair key: -$ gpg --gen-key + $ gpg --gen-key -When gpg asks for e-mail linked the key you *MUST USE* the <committer>@apache.org one. When gpg asks for comment linked the key you *SHOULD USE* "CODE SIGNING KEY" + When gpg asks for e-mail linked the key you *MUST USE* the <committer>@apache.org one. When gpg asks for comment linked the key you *SHOULD USE* "CODE SIGNING KEY" 1. Add the key to [https://people.apache.org/keys/group/sling.asc](https://people.apache.org/keys/group/sling.asc) -1. Type the following command replacing the word `<e-mail>` with your Apache's one (<committer>@apache.org) to get the key signature - -$ gpg --fingerprint <e-mail> - -The key signature is in the output following the `Key fingerprint = ` part. - -1. Add the key signature into the field 'OpenPGP Public Key Primary Fingerprint' in your profile at [https://id.apache.org](https://id.apache.org). - -1. You are *DONE*, but to see the changes on [https://people.apache.org/keys/group/sling.asc](https://people.apache.org/keys/group/sling.asc) you may need to wait a few hours; + 1. Type the following command replacing the word `<e-mail>` with your Apache's one (<committer>@apache.org) to get the key signature + + $ gpg --fingerprint <e-mail> + + The key signature is in the output following the `Key fingerprint = ` part. + + 1. Add the key signature into the field 'OpenPGP Public Key Primary Fingerprint' in your profile at [https://id.apache.org](https://id.apache.org). + + 1. You are *DONE*, but to see the changes on [https://people.apache.org/keys/group/sling.asc](https://people.apache.org/keys/group/sling.asc) you may need to wait a few hours; 1. You also have to add your public key either on `pool.sks-keyservers.net` or `pgp.mit.edu` (for the staging repository). To do so you can follow these steps: -1. Extract the key id from all the secret keys stored in the system: - -$ gpg --list-secret-keys. - -The output is something like this - -gpg --list-secret-keys -/Users/konradwindszus/.gnupg/secring.gpg ----------------------------------------- - -sec 2048R/455ECC7C 2016-01-21 -uid Konrad Windszus <k...@apache.org> -ssb 2048R/226BCE00 2016-01-21 - -The key id in this case is `455ECC7C`. - -1. Send the key towards e.g. `pool.sks-keyservers.net` via - -$ gpg --keyserver pool.sks-keyservers.net --send-key <key-id> - + 1. Extract the key id from all the secret keys stored in the system: + + $ gpg --list-secret-keys. + + The output is something like this + + gpg --list-secret-keys + /Users/konradwindszus/.gnupg/secring.gpg + ---------------------------------------- + + sec 2048R/455ECC7C 2016-01-21 + uid Konrad Windszus <k...@apache.org> + ssb 2048R/226BCE00 2016-01-21 + + The key id in this case is `455ECC7C`. + + 1. Send the key towards e.g. `pool.sks-keyservers.net` via + + $ gpg --keyserver pool.sks-keyservers.net --send-key <key-id> + ## Appendix B: Maven and SCM credentials For running the `mvn release:prepare` command without giving credentials on command line add `svn.apache.org` to your `settings.xml`: -<server> -<id>svn.apache.org</id> -<username>USERNAME</username> -<password>ENCRYPTED_PASSWORD</password> -</server> - + <server> + <id>svn.apache.org</id> + <username>USERNAME</username> + <password>ENCRYPTED_PASSWORD</password> + </server> + ## Appendix C: Deploy bundles on the Sling OBR (obsolete) *Update November 2016: We do now longer maintain the Sling OBR for new releases.* - + We are mainting an OSGi Bundle Repository providing all release of the Sling Bundles. This repository is maintained as part of the Apache Sling site and is available at [http://sling.apache.org/obr/sling.xml](http://sling.apache.org/obr/sling.xml). The source for this page is maintained in the SVN repository below the _site_, that is at [http://svn.apache.org/repos/asf/sling/site/](http://svn.apache.org/repos/asf/sling/site/). To update the Sling OBR repository you must be an Apache Sling Committer since this requires SVN write access. - + To update the OBR you may use the Apache Felix Maven Bundle Plugin which prepares the bundle descriptor to be added to the OBR file. Follow these steps to update the OBR: - + 1. Checkout or update the Site Source + + $ svn checkout https://svn.apache.org/repos/asf/sling/site -$ svn checkout https://svn.apache.org/repos/asf/sling/site - -Note, that you have to checkout the site using the `https` URL, otherwise you will not be able to commit the changes later. - + Note, that you have to checkout the site using the `https` URL, otherwise you will not be able to commit the changes later. + 2. Deploy the Descriptor - -To deploy the project descriptor, checkout the tag of the bundle to deploy and run maven - -$ svn checkout http://svn.apache.org/repos/asf/sling/tags/the_module_tag -$ cd the_module_tag -$ mvn clean install org.apache.felix:maven-bundle-plugin:deploy -DprefixUrl=http://repo1.maven.org/maven2 -DremoteOBR=sling.xml -DaltDeploymentRepository=apache.releases::default::file:///path_to_site_checkout/trunk/content/obr - -This generates the bundle descriptor and adds it to the sling.xml file of your site checkout. -As it also installs a fresh compiled version of the artifacts, it's better to remove that version from your local repository again (A new binary has new checksums etc.). - + + To deploy the project descriptor, checkout the tag of the bundle to deploy and run maven + + $ svn checkout http://svn.apache.org/repos/asf/sling/tags/the_module_tag + $ cd the_module_tag + $ mvn clean install \ + org.apache.felix:maven-bundle-plugin:deploy \ + -DprefixUrl=http://repo1.maven.org/maven2 \ + -DremoteOBR=sling.xml \ + -DaltDeploymentRepository=apache.releases::default::file:///path_to_site_checkout/trunk/content/obr + + This generates the bundle descriptor and adds it to the sling.xml file of your site checkout. + As it also installs a fresh compiled version of the artifacts, it's better to remove that version from your local repository again (A new binary has new checksums etc.). + 2. Variant: Refer to Maven Repository - -Instead of checking out and building the project locally, you may also use the `deploy-file` goal of the Maven Bundle Plugin: - -$ wget http://repo1.maven.org/maven2/org/apache/sling/the_module/version/the_module-version.jar -$ wget http://repo1.maven.org/maven2/org/apache/sling/the_moduleversion/the_module-version.pom -$ mvn org.apache.felix:maven-bundle-plugin:deploy-file -Dfile=the_module-version.jar -DpomFile=the_module-version.pom -DbundleUrl=http://repo1.maven.org/maven2/org/apache/sling/the_module/version/the_module-version.jar -Durl=file:///path_to_site_checkout/obr -DprefixUrl=http://repo1.maven.org/maven2 -DremoteOBR=sling.xml -$ rm the_module-version.jar the_module-version.pom + + Instead of checking out and building the project locally, you may also use the `deploy-file` goal of the Maven Bundle Plugin: + + $ wget http://repo1.maven.org/maven2/org/apache/sling/the_module/version/the_module-version.jar + $ wget http://repo1.maven.org/maven2/org/apache/sling/the_moduleversion/the_module-version.pom + $ mvn org.apache.felix:maven-bundle-plugin:deploy-file \ + -Dfile=the_module-version.jar -DpomFile=the_module-version.pom \ + -DbundleUrl=http://repo1.maven.org/maven2/org/apache/sling/the_module/version/the_module-version.jar \ + -Durl=file:///path_to_site_checkout/obr \ + -DprefixUrl=http://repo1.maven.org/maven2 \ + -DremoteOBR=sling.xml + $ rm the_module-version.jar the_module-version.pom 3. Commit the Site Changes -In the Site checkout folder commit the changes to the `trunk/content/obr/sling.xml` files (you may also review the changes using the `svn diff` command). - -$ svn commit -m"Add Bundle ABC Version X.Y.Z" trunk/content/obr/sling.xml + In the Site checkout folder commit the changes to the `trunk/content/obr/sling.xml` files (you may also review the changes using the `svn diff` command). + + $ svn commit -m"Add Bundle ABC Version X.Y.Z" trunk/content/obr/sling.xml 4. Update the Site -Wait for the buildbot to update the staging area with your site update (see dev list for an email). -Then go to the CMS at [https://cms.apache.org/redirect?uri=http://sling.apache.org/obr](https://cms.apache.org/redirect?uri=http://sling.apache.org/obr) , -update your checkout and then publish the site. + Wait for the buildbot to update the staging area with your site update (see dev list for an email). + Then go to the CMS at [https://cms.apache.org/redirect?uri=http://sling.apache.org/obr](https://cms.apache.org/redirect?uri=http://sling.apache.org/obr) , + update your checkout and then publish the site. ## Appendix D: Deploy Maven plugin documentation (if applicable) @@ -441,15 +453,15 @@ To publish the plugin documentation execute the following steps after the releas 1. Checkout the release tag of the released plugin (or reset your workspace) 2. Build and stage the maven site of the plugin. Note that this *commits* the generated content to the components folder mentioned below. - -$ mvn clean site:site site:stage scm-publish:publish-scm + + $ mvn clean site:site site:stage scm-publish:publish-scm 3. Checkout the 'components' subtree of the Sling website -$ svn checkout https://svn.apache.org/repos/asf/sling/site/trunk/content/components + $ svn checkout https://svn.apache.org/repos/asf/sling/site/trunk/content/components 4. SVN-rename the generated documenation that the site plugin commited to `<plugin-name>-archives/<plugin-name>-LATEST` to `<plugin-name>-archives/<plugin-name>-<version>` - + 5. SVN-remove the existing folder `<plugin-name>` and SVN-copy the folder `<plugin-name>-archives/<plugin-name>-<version>` to `<plugin-name>` 6. Commit the changes.
http://git-wip-us.apache.org/repos/asf/sling-site/blob/53c84cf9/content/documentation/development/repository-based-development.md ---------------------------------------------------------------------- diff --git a/content/documentation/development/repository-based-development.md b/content/documentation/development/repository-based-development.md index ddc7418..71dde6f 100644 --- a/content/documentation/development/repository-based-development.md +++ b/content/documentation/development/repository-based-development.md @@ -1,15 +1,18 @@ -title=Repository Based Development -type=page +title=TODO title for repository-based-development.md +date=1900-01-01 +type=post +tags=blog status=published ~~~~~~ +Title: Repository Based Development [TOC] # WebDAV Support -WebDAV support in Sling is based on the [Simple WebDAV](http://jackrabbit.apache.org/jcr/components/jackrabbit-jcr-server.html#Simple_Webdav_Server) implementation of Apache Jackrabbit which is integrated in the `jcr/webdav` project. This bundle provides WebDAV access to Sling's repository in two flavours: +WebDAV support in Sling is based on the [Simple WebDAV](http://jackrabbit.apache.org/jcr/components/jackrabbit-jcr-server.html#Simple_Webdav_Server) implementation of Apache Jackrabbit which is integrated in the `jcr/webdav` project. This bundle provides WebDAV access to Sling's repository in two flavours: -1. Access to all workspaces of the repository on a separate URI space -- by default rooted at `/dav` in the Sling context -- and +1. Access to all workspaces of the repository on a separate URI space -- by default rooted at `/dav` in the Sling context -- and 2. access to the workspace used by Sling itself at the root of the Sling context. @@ -20,17 +23,17 @@ Consider Sling be installed on a Servlet container in the `/sling` context on `s Please note that accessing the repository in the separate URI space is actually faster, since requests do not pass the Sling resource and script resolution framework but instead hit the Jackrabbit Simple WebDAV Servlet directly. -## Separate URI Space WebDAV +## Separate URI Space WebDAV When accessing the repository through WebDAV in its separate URI Space, the URLs have the following generic structure: -<slingroot>/<prefix>/<workspace>/<item> + <slingroot>/<prefix>/<workspace>/<item> -* `slingroot` is the URL of the Sling web application context. In the above example, this would `http://some.host.net:8080/sling`. -* `prefix` is the URL prefix to address the WebDAV servlet. By default this is set to `/dav` but may be configured to any valid path. -* `workspace` is the name of the workspace to be accessed through WebDAV. -* `item` is the path to the JCR Item to access. + * `slingroot` is the URL of the Sling web application context. In the above example, this would `http://some.host.net:8080/sling`. + * `prefix` is the URL prefix to address the WebDAV servlet. By default this is set to `/dav` but may be configured to any valid path. + * `workspace` is the name of the workspace to be accessed through WebDAV. + * `item` is the path to the JCR Item to access. If you access the WebDAV server at the prefix path -- e.g. `http://localhost:8080/dav` -- you will be redirected to the default workspace with a temporary redirect status 302. Some clients, such as the Linux *davfs*, do not like this redirection and must be configured to explicitly address the default workspace. http://git-wip-us.apache.org/repos/asf/sling-site/blob/53c84cf9/content/documentation/development/resourceresolver-mock.md ---------------------------------------------------------------------- diff --git a/content/documentation/development/resourceresolver-mock.md b/content/documentation/development/resourceresolver-mock.md index 872f387..0e267d2 100644 --- a/content/documentation/development/resourceresolver-mock.md +++ b/content/documentation/development/resourceresolver-mock.md @@ -1,7 +1,10 @@ -title=Resource Resolver Mock -type=page +title=TODO title for resourceresolver-mock.md +date=1900-01-01 +type=post +tags=blog status=published ~~~~~~ +Title: Resource Resolver Mock Mock for the resource resolver / factory for easier testing. It uses an in-memory map for storing the resource data, and supports reading, writing and a certain level of transaction and eventing support. @@ -10,11 +13,11 @@ Mock for the resource resolver / factory for easier testing. It uses an in-memor ## Maven Dependency -#!xml -<dependency> -<groupId>org.apache.sling</groupId> -<artifactId>org.apache.sling.testing.resourceresolver-mock</artifactId> -</dependency> + #!xml + <dependency> + <groupId>org.apache.sling</groupId> + <artifactId>org.apache.sling.testing.resourceresolver-mock</artifactId> + </dependency> See latest version on the [downloads page](/downloads.cgi). @@ -42,9 +45,9 @@ The following features are *not supported*: To create a mocked resource resolver: -#!java -MockResourceResolverFactory factory = new MockResourceResolverFactory(); -ResourceResolver resolver = factory.getResourceResolver(null); + #!java + MockResourceResolverFactory factory = new MockResourceResolverFactory(); + ResourceResolver resolver = factory.getResourceResolver(null); With the resolver you can use all Sling Resource features including reading and writing data using the Sling API. http://git-wip-us.apache.org/repos/asf/sling-site/blob/53c84cf9/content/documentation/development/sling-mock.md ---------------------------------------------------------------------- diff --git a/content/documentation/development/sling-mock.md b/content/documentation/development/sling-mock.md index 2dbb43f..d44e34f 100644 --- a/content/documentation/development/sling-mock.md +++ b/content/documentation/development/sling-mock.md @@ -1,7 +1,10 @@ -title=Sling Mocks -type=page +title=TODO title for sling-mock.md +date=1900-01-01 +type=post +tags=blog status=published ~~~~~~ +Title: Sling Mocks Mock implementation of selected Sling APIs for easier testing. @@ -10,11 +13,11 @@ Mock implementation of selected Sling APIs for easier testing. ## Maven Dependency -#!xml -<dependency> -<groupId>org.apache.sling</groupId> -<artifactId>org.apache.sling.testing.sling-mock</artifactId> -</dependency> + #!xml + <dependency> + <groupId>org.apache.sling</groupId> + <artifactId>org.apache.sling.testing.sling-mock</artifactId> + </dependency> See latest version on the [downloads page](/downloads.cgi). @@ -30,16 +33,16 @@ There are two major version ranges available: The mock implementation supports: * `ResourceResolver` implementation for reading and writing resource data using the Sling Resource API -* Backed by a [mocked][jcr-mock] or real Jackrabbit JCR implementation -* Uses the productive [Sling JCR resource provider implementation][jcr-resource] internally to do the Resource-JCR mapping -* Alternatively the non-JCR mock implementation provided by the -[Sling resourceresolver-mock implementation][resourceresolver-mock] can be used + * Backed by a [mocked][jcr-mock] or real Jackrabbit JCR implementation + * Uses the productive [Sling JCR resource provider implementation][jcr-resource] internally to do the Resource-JCR mapping + * Alternatively the non-JCR mock implementation provided by the + [Sling resourceresolver-mock implementation][resourceresolver-mock] can be used * `AdapterManager` implementation for registering adapter factories and resolving adaptions -* The implementation is thread-safe so it can be used in parallel running unit tests + * The implementation is thread-safe so it can be used in parallel running unit tests * `SlingScriptHelper` implementation providing access to mocked request/response objects and supports getting -OSGi services from the [mocked OSGi][osgi-mock] environment. + OSGi services from the [mocked OSGi][osgi-mock] environment. * Implementations of the servlet-related Sling API classes like `SlingHttpServletRequest` and `SlingHttpServletRequest` -* It is possible to set request data to simulate a certain Sling HTTP request + * It is possible to set request data to simulate a certain Sling HTTP request * Support for Sling Models (Sling Models API 1.1 and Impl 1.1 or higher required) * Additional services `MimeTypeService` * Context Plugins @@ -47,7 +50,7 @@ OSGi services from the [mocked OSGi][osgi-mock] environment. The following features are *not supported*: * It is not possible (nor intended) to really execute sling components/scripts and render their results. -* The goal is to test supporting classes in Sling context, not the sling components/scripts themselves + * The goal is to test supporting classes in Sling context, not the sling components/scripts themselves ### Additional features @@ -55,9 +58,9 @@ The following features are *not supported*: Additional features provided: * `SlingContext` JUnit Rule for easily setting up a Sling Mock environment in your JUnit test cases -* `ContentLoader` supports importing JSON data and binary data into the mock resource hierarchy to easily -prepare a test fixture consisting of a hierarchy of resources and properties. -* The same JSON format can be used that is provided by the Sling GET servlet for output +* `ContentLoader` supports importing JSON data and binary data into the mock resource hierarchy to easily + prepare a test fixture consisting of a hierarchy of resources and properties. + * The same JSON format can be used that is provided by the Sling GET servlet for output * `ContentBuilder` and `ResourceBuilder` make it easier to create resources and properties as test fixture @@ -66,24 +69,24 @@ prepare a test fixture consisting of a hierarchy of resources and properties. ### Sling Context JUnit Rule The Sling mock context can be injected into a JUnit test using a custom JUnit rule named `SlingContext`. -This rules takes care of all initialization and cleanup tasks required to make sure all unit tests can run +This rules takes care of all initialization and cleanup tasks required to make sure all unit tests can run independently (and in parallel, if required). Example: -#!java -public class ExampleTest { + #!java + public class ExampleTest { -@Rule -public final SlingContext context = new SlingContext(); + @Rule + public final SlingContext context = new SlingContext(); -@Test -public void testSomething() { -Resource resource = context.resourceResolver().getResource("/content/sample/en"); -// further testing -} + @Test + public void testSomething() { + Resource resource = context.resourceResolver().getResource("/content/sample/en"); + // further testing + } -} + } It is possible to combine such a unit test rule with a `@RunWith` annotation e.g. for [Mockito JUnit Runner][mockito-testrunner]. @@ -108,13 +111,13 @@ Additionally it supports: The Sling mock context supports different resource resolver types. Example: -#!java -public class ExampleTest { + #!java + public class ExampleTest { -@Rule -public final SlingContext context = new SlingContext(ResourceResolverType.RESOURCERESOLVER_MOCK); + @Rule + public final SlingContext context = new SlingContext(ResourceResolverType.RESOURCERESOLVER_MOCK); -} + } Different resource resolver mock types are supported with pros and cons, see next chapter for details. @@ -122,7 +125,7 @@ Different resource resolver mock types are supported with pros and cons, see nex ### Resource Resolver Types The Sling Mocks resource resolver implementation supports different "types" of adapters for the mocks. -Depending on the type an underlying JCR repository is used or not, and the data is stored in-memory or in a real +Depending on the type an underlying JCR repository is used or not, and the data is stored in-memory or in a real repository. Resource resolver types currently supported: @@ -158,12 +161,12 @@ Resource resolver types currently supported: To use this type you have to declare an additional dependency in your test project: -#!xml -<dependency> -<groupId>org.apache.sling</groupId> -<artifactId>org.apache.sling.testing.sling-mock-oak</artifactId> -<scope>test</scope> -</dependency> + #!xml + <dependency> + <groupId>org.apache.sling</groupId> + <artifactId>org.apache.sling.testing.sling-mock-oak</artifactId> + <scope>test</scope> + </dependency> See latest version on the [downloads page](/downloads.cgi). @@ -172,17 +175,17 @@ See latest version on the [downloads page](/downloads.cgi). * Uses a real JCR Jackrabbit implementation (not Oak) as provided by [sling/commons/testing][sling-commons-testing] * Full JCR/Sling features supported e.g. observations manager, transactions, versioning * Uses the productive [Sling JCR resource provider implementation][jcr-resource] internally to do the Resource-JCR mapping -* Takes some seconds for startup on the first access +* Takes some seconds for startup on the first access * Node types defined in OSGi bundle header 'Sling-Nodetypes' found in MANIFEST.MF files in the classpath are registered automatically. To use this type you have to declare an additional dependency in your test project: -#!xml -<dependency> -<groupId>org.apache.sling</groupId> -<artifactId>org.apache.sling.testing.sling-mock-jackrabbit</artifactId> -<scope>test</scope> -</dependency> + #!xml + <dependency> + <groupId>org.apache.sling</groupId> + <artifactId>org.apache.sling.testing.sling-mock-jackrabbit</artifactId> + <scope>test</scope> + </dependency> See latest version on the [downloads page](/downloads.cgi). @@ -190,7 +193,7 @@ _Remarks on the JCR_JACKRABBIT type:_ * The repository is not cleared for each unit test, so make sure to use a unique node path for each unit test. You may use the `uniquePath()` helper object of the SlingContext rule for this. * The [sling/commons/testing][sling-commons-testing] dependency introduces a lot of further dependencies from -jackrabbit and others, be careful that they do not conflict and are imported in the right order in your test project + jackrabbit and others, be careful that they do not conflict and are imported in the right order in your test project @@ -198,12 +201,12 @@ jackrabbit and others, be careful that they do not conflict and are imported in Example: -#!java -// get a resource resolver -ResourceResolver resolver = MockSling.newResourceResolver(); + #!java + // get a resource resolver + ResourceResolver resolver = MockSling.newResourceResolver(); -// get a resource resolver backed by a specific repository type -ResourceResolver resolver = MockSling.newResourceResolver(ResourceResolverType.JCR_MOCK); + // get a resource resolver backed by a specific repository type + ResourceResolver resolver = MockSling.newResourceResolver(ResourceResolverType.JCR_MOCK); If you use the `SlingContext` JUnit rule you case just use `context.resourceResolver()`. @@ -214,19 +217,19 @@ You can register your own or existing adapter factories to support adaptions e.g Example: -#!java -// register adapter factory -BundleContext bundleContext = MockOsgi.newBundleContext(); -MockSling.setAdapterManagerBundleContext(bundleContext); -bundleContext.registerService(myAdapterFactory); + #!java + // register adapter factory + BundleContext bundleContext = MockOsgi.newBundleContext(); + MockSling.setAdapterManagerBundleContext(bundleContext); + bundleContext.registerService(myAdapterFactory); -// test adaption -MyClass object = resource.adaptTo(MyClass.class); + // test adaption + MyClass object = resource.adaptTo(MyClass.class); -// cleanup after unit test -MockSling.clearAdapterManagerBundleContext(); + // cleanup after unit test + MockSling.clearAdapterManagerBundleContext(); -Make sure you clean up the adapter manager bundle association after running the unit test otherwise it can +Make sure you clean up the adapter manager bundle association after running the unit test otherwise it can interfere with the following tests. If you use the `SlingContext` JUnit rule this is done automatically for you. If you use the `SlingContext` JUnit rule you case just use `context.registerService()`. @@ -236,19 +239,19 @@ If you use the `SlingContext` JUnit rule you case just use `context.registerServ Example: -#!java -// get script helper -SlingScriptHelper scriptHelper = MockSling.newSlingScriptHelper(); + #!java + // get script helper + SlingScriptHelper scriptHelper = MockSling.newSlingScriptHelper(); -// get request -SlingHttpServletRequest request = scriptHelper.getRequest(); + // get request + SlingHttpServletRequest request = scriptHelper.getRequest(); -// get service -MyService object = scriptHelper.getService(MyService.class); + // get service + MyService object = scriptHelper.getService(MyService.class); To support getting OSGi services you have to register them via the `BundleContext` interface of the [JCR Mocks][jcr-mock] before. You can use an alternative factory method for the `SlingScriptHelper` providing -existing instances of request, response and bundle context. +existing instances of request, response and bundle context. If you use the `SlingContext` JUnit rule you case just use `context.slingScriptHelper()`. @@ -257,68 +260,68 @@ If you use the `SlingContext` JUnit rule you case just use `context.slingScriptH Example for preparing a sling request with custom request data: -#!java -// prepare sling request -ResourceResolver resourceResolver = MockSling.newResourceResolver(); -MockSlingHttpServletRequest request = new MockSlingHttpServletRequest(resourceResolver); + #!java + // prepare sling request + ResourceResolver resourceResolver = MockSling.newResourceResolver(); + MockSlingHttpServletRequest request = new MockSlingHttpServletRequest(resourceResolver); -// simulate query string -request.setQueryString("param1=aaa¶m2=bbb"); + // simulate query string + request.setQueryString("param1=aaa¶m2=bbb"); -// alternative - set query parameters as map -request.setParameterMap(ImmutableMap.<String,Object>builder() -.put("param1", "aaa") -.put("param2", "bbb") -.build()); + // alternative - set query parameters as map + request.setParameterMap(ImmutableMap.<String,Object>builder() + .put("param1", "aaa") + .put("param2", "bbb") + .build()); -// set current resource -request.setResource(resourceResolver.getResource("/content/sample")); + // set current resource + request.setResource(resourceResolver.getResource("/content/sample")); -// set sling request path info properties -MockRequestPathInfo requestPathInfo = (MockRequestPathInfo)request.getRequestPathInfo(); -requestPathInfo.setSelectorString("selector1.selector2"); -requestPathInfo.setExtension("html"); + // set sling request path info properties + MockRequestPathInfo requestPathInfo = (MockRequestPathInfo)request.getRequestPathInfo(); + requestPathInfo.setSelectorString("selector1.selector2"); + requestPathInfo.setExtension("html"); -// set method -request.setMethod(HttpConstants.METHOD_POST); + // set method + request.setMethod(HttpConstants.METHOD_POST); -// set attributes -request.setAttribute("attr1", "value1"); + // set attributes + request.setAttribute("attr1", "value1"); -// set headers -request.addHeader("header1", "value1"); + // set headers + request.addHeader("header1", "value1"); -// set cookies -request.addCookie(new Cookie("cookie1", "value1")); + // set cookies + request.addCookie(new Cookie("cookie1", "value1")); ### SlingHttpServletResponse Example for preparing a sling response which can collect the data that was written to it: -#!java -// prepare sling response -MockSlingHttpServletResponse response = new MockSlingHttpServletResponse(); + #!java + // prepare sling response + MockSlingHttpServletResponse response = new MockSlingHttpServletResponse(); -// execute your unit test code that writes to the response... + // execute your unit test code that writes to the response... -// validate status code -assertEquals(HttpServletResponse.SC_OK, response.getStatus()); + // validate status code + assertEquals(HttpServletResponse.SC_OK, response.getStatus()); -// validate content type and content length -assertEquals("text/plain;charset=UTF-8", response.getContentType()); -assertEquals(CharEncoding.UTF_8, response.getCharacterEncoding()); -assertEquals(55, response.getContentLength()); + // validate content type and content length + assertEquals("text/plain;charset=UTF-8", response.getContentType()); + assertEquals(CharEncoding.UTF_8, response.getCharacterEncoding()); + assertEquals(55, response.getContentLength()); -// validate headers -assertTrue(response.containsHeader("header1")); -assertEquals("5", response.getHeader("header2")); + // validate headers + assertTrue(response.containsHeader("header1")); + assertEquals("5", response.getHeader("header2")); -// validate response body as string -assertEquals(TEST_CONTENT, response.getOutputAsString()); + // validate response body as string + assertEquals(TEST_CONTENT, response.getOutputAsString()); -// validate response body as binary data -assertArrayEquals(TEST_DATA, response.getOutput()); + // validate response body as binary data + assertArrayEquals(TEST_DATA, response.getOutput()); ### Import resource data from JSON file in classpath @@ -328,32 +331,32 @@ in the classpath beneath the unit tests. This data can be used as text fixture f Example JSON data: -#!json -{ -"jcr:primaryType": "app:Page", -"jcr:content": { -"jcr:primaryType": "app:PageContent", -"jcr:title": "English", -"app:template": "/apps/sample/templates/homepage", -"sling:resourceType": "sample/components/homepage", -"jcr:createdBy": "admin", -"jcr:created": "Thu Aug 07 2014 16:32:59 GMT+0200", -"par": { -"jcr:primaryType": "nt:unstructured", -"sling:resourceType": "foundation/components/parsys", -"colctrl": { -"jcr:primaryType": "nt:unstructured", -"layout": "2;colctrl-lt0", -"sling:resourceType": "foundation/components/parsys/colctrl" -} -} -} -} + #!json + { + "jcr:primaryType": "app:Page", + "jcr:content": { + "jcr:primaryType": "app:PageContent", + "jcr:title": "English", + "app:template": "/apps/sample/templates/homepage", + "sling:resourceType": "sample/components/homepage", + "jcr:createdBy": "admin", + "jcr:created": "Thu Aug 07 2014 16:32:59 GMT+0200", + "par": { + "jcr:primaryType": "nt:unstructured", + "sling:resourceType": "foundation/components/parsys", + "colctrl": { + "jcr:primaryType": "nt:unstructured", + "layout": "2;colctrl-lt0", + "sling:resourceType": "foundation/components/parsys/colctrl" + } + } + } + } Example code to import the JSON data: -#!java -context.load().json("/sample-data.json", "/content/sample/en"); + #!java + context.load().json("/sample-data.json", "/content/sample/en"); This codes creates a new resource at `/content/sample/en` (and - if not existent - the parent resources) and imports the JSON data to this node. It can be accessed using the Sling Resource or JCR API afterwards. @@ -362,14 +365,14 @@ imports the JSON data to this node. It can be accessed using the Sling Resource ### Import binary data from file in classpath With the `ContentLoader` it is possible to import a binary file stored in the classpath beneath the unit tests. -The data is stored using a nt:file/nt:resource or nt:resource node type. +The data is stored using a nt:file/nt:resource or nt:resource node type. Example code to import a binary file: -#!java -context.load().binaryFile("/sample-file.gif", "/content/binary/sample-file.gif"); + #!java + context.load().binaryFile("/sample-file.gif", "/content/binary/sample-file.gif"); -This codes creates a new resource at `/content/binary/sample-file.gif` (and - if not existent - the parent +This codes creates a new resource at `/content/binary/sample-file.gif` (and - if not existent - the parent resources) and imports the binary data to a jcr:content subnode. @@ -387,18 +390,18 @@ The entry point for the `ContentBuilder` is the `create()` method on the Sling c Example: -#!java -context.create().resource("/content/test1", ImmutableMap.<String, Object>builder() -.put("prop1", "value1") -.put("prop2", "value2") -.build()); + #!java + context.create().resource("/content/test1", ImmutableMap.<String, Object>builder() + .put("prop1", "value1") + .put("prop2", "value2") + .build()); Simplified syntax without using a map: -#!java -context.create().resource("/content/test1", -"prop1", "value1", -"prop2", "value2"); + #!java + context.create().resource("/content/test1", + "prop1", "value1", + "prop2", "value2"); If you use the `SlingContext` JUnit rule you case just use `context.create()`. @@ -410,12 +413,12 @@ The entry point for the `ResourceBuilder` is the `build()` method on the Sling c Example: -#!java -context.build().resource("/content/test1") -.siblingsMode() -.resource("test1.1", "stringParam", "configValue1.1") -.resource("test1.2", "stringParam", "configValue1.2") -.resource("test1.2", "stringParam", "configValue1.3"); + #!java + context.build().resource("/content/test1") + .siblingsMode() + .resource("test1.1", "stringParam", "configValue1.1") + .resource("test1.2", "stringParam", "configValue1.2") + .resource("test1.2", "stringParam", "configValue1.3"); See JavaDocs of the class `org.apache.sling.resourcebuilder.api.ResourceBuilder` for a detailed documentation. @@ -428,11 +431,11 @@ To define a plugin implement the `org.apache.sling.testing.mock.osgi.context.Con To use a plugin in your unit test class, use the `SlingContextBuilder` class instead of directly instantiating the `SlingContext`class. This allows you in a fluent style to configure more options, with the `plugin(...)` method you can add one or more plugins. -Example: +Example: -#!java -@Rule -public SlingContext context = new SlingContextBuilder().plugin(MY_PLUGIN).build(); + #!java + @Rule + public SlingContext context = new SlingContextBuilder().plugin(MY_PLUGIN).build(); More examples: http://git-wip-us.apache.org/repos/asf/sling-site/blob/53c84cf9/content/documentation/development/sling-testing-tools.md ---------------------------------------------------------------------- diff --git a/content/documentation/development/sling-testing-tools.md b/content/documentation/development/sling-testing-tools.md index 0c02530..28ef388 100644 --- a/content/documentation/development/sling-testing-tools.md +++ b/content/documentation/development/sling-testing-tools.md @@ -1,14 +1,17 @@ -title=Sling Testing Tools -type=page +title=TODO title for sling-testing-tools.md +date=1900-01-01 +type=post +tags=blog status=published ~~~~~~ +Title: Sling Testing Tools <div class="warning"> While this information is still valid, we recommend using the tools and techniques described -in the newer "Junit Server-Side Tests Support" page instead, see link below. +in the newer "Junit Server-Side Tests Support" page instead, see link below. </div> -As mentioned above, this is now replaced by the [Junit Server-Side Tests Support](/documentation/bundles/org-apache-sling-junit-bundles.html) page. +As mentioned above, this is now replaced by the [Junit Server-Side Tests Support](/documentation/bundles/org-apache-sling-junit-bundles.html) page. Sling provides a number of testing tools to support the following use cases: @@ -39,7 +42,7 @@ Note that the JUnitServlet does not require authentication, so it would allow an For tighter integration with Sling, the alternate `SlingJUnitServlet` is registered with the `sling/junit/testing` resource type and `.junit` selector, if the bundle is running in a Sling system. Using this servlet instead of the plain JUnitServlet also allows Sling authentication to be used for running the tests, and the standard Sling request processing is used, including servlet filters for example. </div> -To try the JUnitServlet interactively, install a bundle that contains tests registered via the `Sling-Test-Regexp=.*Test` bundle header. +To try the JUnitServlet interactively, install a bundle that contains tests registered via the `Sling-Test-Regexp=.*Test` bundle header. The JUnit core services use this regular expression to select which classes of the test bundle should be executed as JUnit tests. @@ -55,23 +58,23 @@ The `@TestReference` annotation is used to inject OSGi services in tests that ar ## Curl examples Here's an example executing a few tests using curl: -$ curl -X POST http://localhost:8080/system/sling/junit/org.apache.sling.testing.samples.sampletests.JUnit.json -[{ -"INFO_TYPE": "test", -"description": "testPasses(org.apache.sling.testing.samples.sampletests.JUnit3Test)" -},{ -"INFO_TYPE": "test", -"description": "testPasses(org.apache.sling.testing.samples.sampletests.JUnit4Test)" -},{ -"INFO_TYPE": "test", -"description": "testRequiresBefore(org.apache.sling.testing.samples.sampletests.JUnit4Test)" -} -] + $ curl -X POST http://localhost:8080/system/sling/junit/org.apache.sling.testing.samples.sampletests.JUnit.json + [{ + "INFO_TYPE": "test", + "description": "testPasses(org.apache.sling.testing.samples.sampletests.JUnit3Test)" + },{ + "INFO_TYPE": "test", + "description": "testPasses(org.apache.sling.testing.samples.sampletests.JUnit4Test)" + },{ + "INFO_TYPE": "test", + "description": "testRequiresBefore(org.apache.sling.testing.samples.sampletests.JUnit4Test)" + } + ] And another example with a test that fails: -$ curl -X POST http://localhost:8080/system/sling/junit/org.apache.sling.testing.samples.failingtests.JUnit4FailingTest.json + $ curl -X POST http://localhost:8080/system/sling/junit/org.apache.sling.testing.samples.failingtests.JUnit4FailingTest.json # Scriptable server-side tests If the [org.apache.sling.junit.scriptable](http://svn.apache.org/repos/asf/sling/trunk/testing/junit/scriptable) bundle is active in a Sling system, (in addition to the `org.apache.sling.junit.core` bundle), scriptable tests can be executed by the `JUnitServlet` according to the following rules: @@ -84,29 +87,29 @@ The [ScriptableTestsTest](http://svn.apache.org/repos/asf/sling/trunk/testing/sa Here's a minimal example that sets up and executes a scriptable test: -$ curl -u admin:admin -Fjcr:primaryNodeType=sling:Folder -Fsling:resourceType=foo -Fjcr:mixinTypes=sling:Test http://localhost:8080/apps/foo -... -$ echo TEST_PASSED > /tmp/test.txt.esp ; curl -u admin:admin -T/tmp/test.txt.esp http://localhost:8080/apps/foo/test.txt.esp - + $ curl -u admin:admin -Fjcr:primaryNodeType=sling:Folder -Fsling:resourceType=foo -Fjcr:mixinTypes=sling:Test http://localhost:8080/apps/foo + ... + $ echo TEST_PASSED > /tmp/test.txt.esp ; curl -u admin:admin -T/tmp/test.txt.esp http://localhost:8080/apps/foo/test.txt.esp + At this point, foo.test.txt is what the scriptable test framework will request, and that outputs just TEST_PASSED: - -$ curl -u admin:admin http://localhost:8080/apps/foo.test.txt -TEST_PASSED - + + $ curl -u admin:admin http://localhost:8080/apps/foo.test.txt + TEST_PASSED + And a POST to the JUnit servlet returns information on the test's execution: -curl -u admin:admin -XPOST http://localhost:8080/system/sling/junit/org.apache.sling.junit.scriptable.ScriptableTestsProvider.json -[{ -"INFO_TYPE": "test", -"description": "verifyContent[0](org.apache.sling.junit.scriptable.TestAllPaths)", -"test_metadata": { -"test_execution_time_msec": 2 -} -} -] + curl -u admin:admin -XPOST http://localhost:8080/system/sling/junit/org.apache.sling.junit.scriptable.ScriptableTestsProvider.json + [{ + "INFO_TYPE": "test", + "description": "verifyContent[0](org.apache.sling.junit.scriptable.TestAllPaths)", + "test_metadata": { + "test_execution_time_msec": 2 + } + } + ] Test failures would be included in this JSON representation - you can test that by modifying the script to fail and making the -same request again. +same request again. # Integration tests example The [testing/samples/integration-tests](http://svn.apache.org/repos/asf/sling/trunk/testing/samples/integration-tests) module runs some simple integration tests against a Sling Launchpad instance that's setup from scratch before running the tests. @@ -121,7 +124,7 @@ The following steps are executed in the `integration-test` phase of this module' 1. A random port number for the Sling server is selected by the Maven build helper plugin, unless explicitely set (see pom.xml for such options). 1. Additional bundles, defined in the module's pom, are downloaded from the Maven repository in the `target/sling/additional-bundles` folder. -1. The first test that inherits from the [SlingTestBase](https://svn.apache.org/repos/asf/sling/trunk/testing/tools/src/main/java/org/apache/sling/testing/tools/sling/SlingTestBase.java) class causes the Sling runnable jar (defined as a dependency in the module's pom) to be started. +1. The first test that inherits from the [SlingTestBase](https://svn.apache.org/repos/asf/sling/trunk/testing/tools/src/main/java/org/apache/sling/testing/tools/sling/SlingTestBase.java) class causes the Sling runnable jar (defined as a dependency in the module's pom) to be started. 1. The `SlingTestBase` class waits for the Sling server to be ready, based on URLs and expected responses defined in the pom. 1. The `SlingTestBase` class installs and starts the bundles found in the `target/sling/additional-bundles` folder. 1. The test can now either test Sling directly via its http interface, or use the JUnitServlet to execute server-side tests contributed by bundles or scripts, as described above. @@ -132,8 +135,8 @@ If `-DkeepJarRunning` is used on the Maven command line, the Sling runnable jar ## Running tests against existing server -Instead of provisioning a completely new Sling server, the ITs can also be executed on an already existing server instance. For that the -`test-server-url` system property has to point to the existing server url. +Instead of provisioning a completely new Sling server, the ITs can also be executed on an already existing server instance. For that the +`test-server-url` system property has to point to the existing server url. Additional bundles can still be deployed by using the `sling.additional.bundle.<num>` system property. Optionally, the additional bundles can be undeployed after the execution of the IT by setting `additional.bundles.uninstall` to `true`. (since Sling Testing Tools 1.0.12, [SLING-4819](https://issues.apache.org/jira/browse/SLING-4819)) @@ -158,8 +161,8 @@ The [ExampleRemoteTest](https://svn.apache.org/repos/asf/sling/trunk/testing/jun # Debugging ITs The JVM is usually forked twice during the execution of integration tests. The first time by the `maven-surefire-plugin` which executes the client-side (i.e. Maven-side) part of the tests. To debug this side the option `-Dmaven.surefire.debug` can be used which waits for a debugger to be attached on port 5005 before the (client-side) test is executed. More information is available in the [documentation of the maven-surefire-plugin](http://maven.apache.org/surefire/maven-surefire-plugin/examples/debugging.html). -Then the `JarExecutor` is forking the VM a second time to start the server (this does not happen if connecting to an already running instance). The system environment variable `jar.executor.vm.options` can be used to start that VM with debug options. All debug options are described at the [JPDA documentation](http://docs.oracle.com/javase/7/docs/technotes/guides/jpda/conninv.html#Invocation). If running +Then the `JarExecutor` is forking the VM a second time to start the server (this does not happen if connecting to an already running instance). The system environment variable `jar.executor.vm.options` can be used to start that VM with debug options. All debug options are described at the [JPDA documentation](http://docs.oracle.com/javase/7/docs/technotes/guides/jpda/conninv.html#Invocation). If running -mvn test -Djar.executor.vm.options="-agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=8000" + mvn test -Djar.executor.vm.options="-agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=8000" the server start is interrupted until a debugger is connected on port 8000. http://git-wip-us.apache.org/repos/asf/sling-site/blob/53c84cf9/content/documentation/development/sling.md ---------------------------------------------------------------------- diff --git a/content/documentation/development/sling.md b/content/documentation/development/sling.md index 4787b7a..fc866ad 100644 --- a/content/documentation/development/sling.md +++ b/content/documentation/development/sling.md @@ -1,6 +1,9 @@ -title=Maven Sling Plugin -type=page +title=TODO title for sling.md +date=1900-01-01 +type=post +tags=blog status=published ~~~~~~ +Title: Maven Sling Plugin See [Apache Maven Sling Plugin documentation](http://sling.apache.org/components/maven-sling-plugin/).
