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/
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.
Do the following:
Create a new client workspace and connect it to stream
//workshop/main
.
Sync workspace to head.
Install vagrant, VirtualBox.
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.
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.
Find an editor/IDE that supports xdebug.
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
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.
For the workshop project we store password in two places:
Logger::log(Logger::ERR, 'Mon canard est en feu!);
php index.php activity delete -i <key>
Per Geoff, "Yeah, that breaks all the time."
p4 keys -e 'swarm-comments*' |grep blah
php -r "echo str_pad(dechex(0xFFFFFFFF - $key), 8, '0', STR_PAD_LEFT);"
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.
curl -X DELETE 'http://swarm-host/project/delete/packages-test' -u "P4USER:P4TICKET"
From @cchoi:
curl 'http://swarm_url/api/v1/reviews?fields=id&change=CHANGELIST'
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
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 <key> 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 ```