From a2de17dcce44d7bb96773579c5bfc9b5cc9fd8e6 Mon Sep 17 00:00:00 2001 From: Robert Knight Date: Fri, 31 Mar 2017 10:44:13 +0100 Subject: [PATCH 1/3] Add docs explaining how to test the client on a real mobile device Testing the client on a mobile device currently requires several steps which will be non-obvious to new developers. Add documentation to guide users through the process. --- docs/developers/index.rst | 3 ++- docs/developers/mobile.md | 34 ++++++++++++++++++++++++++++++++++ 2 files changed, 36 insertions(+), 1 deletion(-) create mode 100644 docs/developers/mobile.md diff --git a/docs/developers/index.rst b/docs/developers/index.rst index 6ccbb4283d6..40d64e14ba6 100644 --- a/docs/developers/index.rst +++ b/docs/developers/index.rst @@ -8,6 +8,7 @@ the Hypothesis client. :maxdepth: 2 developing - security envvars + mobile + security arch/index diff --git a/docs/developers/mobile.md b/docs/developers/mobile.md new file mode 100644 index 00000000000..30e82622f9d --- /dev/null +++ b/docs/developers/mobile.md @@ -0,0 +1,34 @@ +# Mobile Development + +## Testing the client on a mobile device + +If you have made changes to the client that could affect the mobile experience, it is a good idea to test them on a real device. Such changes should ideally be tested with at least current versions of iOS Safari and Chrome for Android. + +1. Make sure your development system and mobile device are on the same local network. +1. Get the IP address or host name of your development system (`$HOSTNAME` in the steps below). You can do this using the `hostname` terminal command on Mac/Linux. +1. Configure the "h" service to allow incoming connections from other systems by editing `conf/development-app.ini` and changing the `host` setting from `localhost` to `0.0.0.0`. +1. Configure the "h" service to load the client from this host and start the dev + server: + ```sh + # In the "h" repository + + # Configure the URL that the client is loaded from in pages + # that embed Hypothesis + export CLIENT_URL=http://$HOSTNAME:3001/hypothesis + + make dev + ``` +1. Configure the client to load assets from this hostname and start the dev + server: + ```sh + # In the "client" repository + + # Set URL which sidebar app ("app.html") is loaded from + export H_SERVICE_URL=http://$HOSTNAME:5000 + # Set hostname used when generating client asset URLs + export PACKAGE_SERVER_HOSTNAME=$HOSTNAME + + gulp watch + ``` + When `gulp watch` runs, it will print out the URLs used for the "h" service and client assets. These should include `$HOSTNAME` instead of `localhost`. +1. On your mobile device, go to a page which has the client embedded such as `http://$HOSTNAME:3000` or `http://$HOSTNAME:5000/docs/help`. From 3951aa266f230c10cbac2edcffe4b6139b25263f Mon Sep 17 00:00:00 2001 From: Robert Knight Date: Mon, 3 Apr 2017 11:44:54 +0100 Subject: [PATCH 2/3] Address CR feedback * Add note about possible need to add `.local` or `.home` suffix or use IP address instead of hostname. * Use title case for heading. --- docs/developers/mobile.md | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/docs/developers/mobile.md b/docs/developers/mobile.md index 30e82622f9d..fe0bb465ee0 100644 --- a/docs/developers/mobile.md +++ b/docs/developers/mobile.md @@ -1,12 +1,17 @@ # Mobile Development -## Testing the client on a mobile device +## Testing the Client on a Mobile Device If you have made changes to the client that could affect the mobile experience, it is a good idea to test them on a real device. Such changes should ideally be tested with at least current versions of iOS Safari and Chrome for Android. 1. Make sure your development system and mobile device are on the same local network. -1. Get the IP address or host name of your development system (`$HOSTNAME` in the steps below). You can do this using the `hostname` terminal command on Mac/Linux. 1. Configure the "h" service to allow incoming connections from other systems by editing `conf/development-app.ini` and changing the `host` setting from `localhost` to `0.0.0.0`. +1. Get the IP address or host name of your development system (`$HOSTNAME` in the steps below). You can do this using the `hostname` terminal command on Mac/Linux. + + **Tip:** _If the output of `hostname` does not include a `.home` or `.local` + suffix, you may need to append `.local` to get a host name that is accessible from + other devices on the network. If you have problems using the host name, try + using the IP address instead._ 1. Configure the "h" service to load the client from this host and start the dev server: ```sh @@ -30,5 +35,5 @@ If you have made changes to the client that could affect the mobile experience, gulp watch ``` - When `gulp watch` runs, it will print out the URLs used for the "h" service and client assets. These should include `$HOSTNAME` instead of `localhost`. + **Tip:** _When `gulp watch` runs, it will print out the URLs used for the "h" service and client assets. These should include `$HOSTNAME` instead of `localhost`._ 1. On your mobile device, go to a page which has the client embedded such as `http://$HOSTNAME:3000` or `http://$HOSTNAME:5000/docs/help`. From 071811d3ecf2855d09532c30db8267a404038929 Mon Sep 17 00:00:00 2001 From: Robert Knight Date: Mon, 3 Apr 2017 17:07:04 +0100 Subject: [PATCH 3/3] Use `` instead of $HOSTNAME Use angle brackets to indicate that HOSTNAME is a placeholder rather than a dollar-sign to avoid confusion with the `$HOSTNAME` env var. --- docs/developers/mobile.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/developers/mobile.md b/docs/developers/mobile.md index fe0bb465ee0..ee4494f0517 100644 --- a/docs/developers/mobile.md +++ b/docs/developers/mobile.md @@ -6,7 +6,7 @@ If you have made changes to the client that could affect the mobile experience, 1. Make sure your development system and mobile device are on the same local network. 1. Configure the "h" service to allow incoming connections from other systems by editing `conf/development-app.ini` and changing the `host` setting from `localhost` to `0.0.0.0`. -1. Get the IP address or host name of your development system (`$HOSTNAME` in the steps below). You can do this using the `hostname` terminal command on Mac/Linux. +1. Get the IP address or host name of your development system (`` in the steps below). You can do this using the `hostname` terminal command on Mac/Linux. **Tip:** _If the output of `hostname` does not include a `.home` or `.local` suffix, you may need to append `.local` to get a host name that is accessible from @@ -19,7 +19,7 @@ If you have made changes to the client that could affect the mobile experience, # Configure the URL that the client is loaded from in pages # that embed Hypothesis - export CLIENT_URL=http://$HOSTNAME:3001/hypothesis + export CLIENT_URL=http://:3001/hypothesis make dev ``` @@ -29,11 +29,11 @@ If you have made changes to the client that could affect the mobile experience, # In the "client" repository # Set URL which sidebar app ("app.html") is loaded from - export H_SERVICE_URL=http://$HOSTNAME:5000 + export H_SERVICE_URL=http://:5000 # Set hostname used when generating client asset URLs - export PACKAGE_SERVER_HOSTNAME=$HOSTNAME + export PACKAGE_SERVER_HOSTNAME= gulp watch ``` - **Tip:** _When `gulp watch` runs, it will print out the URLs used for the "h" service and client assets. These should include `$HOSTNAME` instead of `localhost`._ -1. On your mobile device, go to a page which has the client embedded such as `http://$HOSTNAME:3000` or `http://$HOSTNAME:5000/docs/help`. + **Tip:** _When `gulp watch` runs, it will print out the URLs used for the "h" service and client assets. These should include `` instead of `localhost`._ +1. On your mobile device, go to a page which has the client embedded such as `http://:3000` or `http://:5000/docs/help`.