FIXME: https://swarm.perforce.com/projects/workshop/files/main/swarm/tests/phpunit https://swarm.perforce.com/projects/workshop/files/main/swarm/module/Projects/test https://swarm.perforce.com/projects/workshop/files/main/swarm/build.xml http://jenkins.bnr.perforce.com/computer/workshop-ub1204-x64/ # Who is this for # This document is for anyone who want to start hacking on the workshop project and expect minimal knowledge to PHP/Zend/tooling around the project. The Workshop project is basically swarm (//depot/main/swarm/...) with custom modules. Including but not limited to: ``` //workshop/main/swarm/module/Application/... //workshop/main/swarm/module/Markdown/... //workshop/main/swarm/module/Workshop/... ``` If you want to learn about the infrastructure of things, see [infra.md][infra.md]. Being on the depot this is a live document - so please add/remove/update anything as you see fit. # Setting up your development environment # Do the following: - Create a new client workspace and connect it to stream `//workshop/main`. - Sync workspace to head. - Install [vagrant](http://vagrantup.com), [VirtualBox](https://www.virtualbox.org). - Install the `vagrant-cachier` plugin with `vagrant plugin install vagrant-cachier`. This is used to cache packages used within your VMs. - `cd` into the //workshop/main/swarm directory in your workspace and run: `vagrant up` - Get a coffee and keep reading this document. # Testing # To run all test cases, run the following command at top level directory (`//workshop/main/swarm`): ``` ant test-unit-module ``` You can run just one module's tests from `module/Modulename/test/` with `phpunit`. `--stderr` sends output to stderr. The `--filter testFunctionName` option lets you limit it to a single test. `ant php-codesniffer` for style checking. # Debugging # - Find an editor/IDE that supports [xdebug](http://xdebug.org/docs/remote). - load the xdebug.so to your PHP installation and configure it for remote debugging (this is done for you in the Vagrant config `manifests/swarm.pp`): ``` zend_extension=/path/to/xdebug/such/as/usr/lib/php5/20090626/xdebug.so xdebug.remote_enable=On xdebug.remote_handler=dbgp ; so xdebug gets the IP address of the xdebug client from the HTTP header xdebug.remote_connect_back=1 xdebug.remote_port=9000 ; remote_log is useful for troubleshooting network-related issues xdebug.remote_log=/tmp/xdebug.log xdebug.remote_mode=req xdebug.force_display_errors=1 ``` Read the fine docs for more options: [http://xdebug.org/docs/all_settings](http://xdebug.org/docs/all_settings) # Deploying # From @tgray: - `cap -T` lists all the tasks - `cap staging` deploy runs "staging" and "deploy" - `cap production deploy` to push to prod - and `cap production deploy:rollback` is your friend. On `wayfarer-swarm*` make sure that you are in the `www-data` group with `sudo` privilege. # Passwords # For the workshop project we store password in two places: - [P4D HOST]:/p4/common/bin/adminpass (for the SDP) - [SWARM HOST]:/var/www/swarm/shared/data/password (for Capistrano) # Logging properly ``` Logger::log(Logger::ERR, 'Mon canard est en feu!); ``` # Other random notes # ## How to delete a comment incorrectly ## php index.php activity delete -i Per Geoff, "Yeah, that breaks all the time." ## How to dig up key ids ## p4 keys -e 'swarm-comments*' |grep blah php -r "echo str_pad(dechex(0xFFFFFFFF - $key), 8, '0', STR_PAD_LEFT);" # RESTful API # ## Adding a project ## From Stew via Chris: ``` curl 'http://swarm_url/project/add' -u 'adminuser:ticket' \ -d'name=project_name&description=project_description&members[]=member1&members[]=member2&owners=project_owner&branches[0][name]=branch_1_name&branches[0][paths]="//depot/path/to/branch_1/..."&branches[1][name]=branch_2_name&branches[1][paths]="//depot/path/to/branch_2/…"' curl 'http://swarm_url/project/add' -u 'adminuser:ticket' \ -d'name=testing_project&description=test_project&members[]=bruno&members[]=cchoi&owners=bruno&branches[0][name]=branch_one&branches[0][paths]="//depot/Jam/MAIN/..."&branches[1][name]=branch_two&branches[1][paths]="//depot/Jam/MAIN/src/..."' ``` `/project/add` is the URL (/object/action) to add a new project. `adminuser:ticket` is Perforce admin user and the user’s ticket value. As you will be giving exclusive rights to admin user to create a project in Swarm, a user account with admin level or higher privileges. `name` is the key for adding the name of the new project you are creating. `description` is the key for adding the description of the project. `members[]` is the key for adding members to the project. You can add another member by adding additional `members[]=useid`. `owners` is the key for adding owner of the project, this will also enable the "Only Owners and Administrators can edit the project" option. `branches[n][name]` is the key for specifying the name of the first branch you add. `branches[n][paths]` is the key for specifying the depot path of the first branch. To add a branch to a project, these two keys must be specified at the same time in the same command. ## Deleting a project ``` curl -X DELETE 'http://swarm-host/project/delete/packages-test' -u "P4USER:P4TICKET" ``` ## Lookup review ids by change number ## From @cchoi: ``` curl 'http://swarm_url/api/v1/reviews?fields=id&change=CHANGELIST' ``` ## Commeting Ref: http://p4intra.perforce.com/pipermail/swarm/2015-July/006336.html Adding a simple review-level comment: ``` curl -u USERNAME -pPASSWORD_OR_TICKET -d "topic=reviews/REVIEW_NUMBER" -d user=USERNAME -d body=COMMENT_GOES_HERE http://swarmhost/comments/add ``` Adding a review-level comment task: ``` curl -u USERNAME -pPASSWORD_OR_TICKET -d "topic=reviews/REVIEW_NUMBER" -d user=USERNAME -d body=COMMENT_GOES_HERE -d taskState=open http://swarmhost/comments/add ``` Adding a line-level comment: ``` curl -u USERNAME -pPASSWORD_OR_TICKET -d "topic=reviews/REVIEW_NUMBER" -d user=USERNAME -d body=COMMENT_GOES_HERE -d context=CONTEXT_GOES_HERE http://swarmhost/comments/add ``` The trick for CONTEXT_GOES_HERE is that it needs to contain a URL-encoded JSON string that resembles the following: ``` {"file":"//depot/path/to/file.txt","rightLine":LINE_NUMBER,"review":REVIEW_NUMBER} ``` After URL-encoding, the string will look similar to this: ``` %7B%22file%22%3A%22%2F%2Fdepot%2Fpath%2Fto%2Ffile.txt%22%2C%22rightLine%22%3ALINE_NUMEBR%2C%22review%22%3AREVIEW_NUMBER%7D ```