~nskaggs/help-app/functional-test-template

« back to all changes in this revision

Viewing changes to HACKING

  • Committer: nskaggs
  • Date: 2015-05-26 19:27:15 UTC
  • Revision ID: nicholas.skaggs@canonical.com-20150526192715-xc3qx84my15757g5
fix unwanted whitespace diffs

Show diffs side-by-side

added added

removed removed

Lines of Context:
22
22
-----------------------
23
23
 
24
24
Our work-flow is a bit special, so bear with us for a while. If you just want
25
 
to start adding content, skip this section. The sections below should
 
25
to start adding content, skip this section. The sections below should 
26
26
probably be enough for that.
27
27
 
28
28
We had a couple of requirements when we started this project:
36
36
pelican and po4a on the content side, the Ubuntu HTML5 UI toolkit and
37
37
the Ubuntu Web Guidelines on the display side.
38
38
 
39
 
 * po4a is used to extract translatable messages from the Markdown
40
 
   content, so that we can get .pot and .po files which are understood by
 
39
 * po4a is used to extract translatable messages from the Markdown 
 
40
   content, so that we can get .pot and .po files which are understood by 
41
41
   Launchpad. We also use po4a to generate translated Markdown files.
42
42
 * pelican takes care of generating HTML from the translated Markdown
43
43
   files. It can build into different output directories, using different
73
73
Prerequisites
74
74
-------------
75
75
 
76
 
Note: if you are still on anything before vivid (15.04) (ie: trusty, utopic,
 
76
Note: if you are still on anything before vivid (15.04) (ie: trusty, utopic, 
77
77
etc.), please add the following PPA:
78
78
 
79
79
  sudo add-apt-repository ppa:ubuntu-touch-coreapps-drivers/collection
85
85
Before you get started, run:
86
86
 
87
87
  sudo apt install python-pelican po4a make bzrtools \
88
 
    ubuntu-html5-ui-toolkit python3-polib python3-magic \
89
 
    python3-markdown pep8 pyflakes python-magic python-polib
 
88
        ubuntu-html5-ui-toolkit python3-polib python3-magic \
 
89
        python3-markdown pep8 pyflakes python-magic python-polib
90
90
 
91
91
This will install the necessary files, so you can build the app or web build
92
92
locally and check if your changes actually make sense and look and work well.
98
98
This app is structured in a very simple way. All the content is and all your
99
99
edits happen in
100
100
 
101
 
    ./content/pages/
 
101
        ./content/pages/
102
102
 
103
 
The markup for the text is Markdown, which is very easy to learn. Just have
104
 
a look at http://daringfireball.net/projects/markdown/ and some of the
 
103
The markup for the text is Markdown, which is very easy to learn. Just have 
 
104
a look at http://daringfireball.net/projects/markdown/ and some of the 
105
105
existing files to get started.
106
106
 
107
107
Once you're happy with your edits, change to the top-level directory and run
108
108
 
109
 
    make app
 
109
        make app
110
110
 
111
111
This will also generate translated pages.
112
112
 
115
115
To launch the app, you can use ubuntu-html5-app-launcher in the www dir, or
116
116
just call
117
117
 
118
 
    make launch
 
118
        make launch
119
119
 
120
120
(This will also run the 'make app' command for you.)
121
121
 
126
126
To create a click package (for example, if you want to test it on your
127
127
device), just run
128
128
 
129
 
    make click
 
129
        make click
130
130
 
131
131
in the top-level directory.
132
132
 
137
137
We also want to publish this information on the web. To start a 'web' build
138
138
of the content, just run
139
139
 
140
 
    make web
 
140
        make web
141
141
 
142
142
Find the resulting files in the ./build/web directory.
143
143
 
144
 
To update the publishing branch (you need to be member of ~help-app-dev),
 
144
To update the publishing branch (you need to be member of ~help-app-dev), 
145
145
run
146
146
 
147
 
    make web-publish
 
147
        make web-publish
148
148
 
149
 
We plan to make use of
 
149
We plan to make use of 
150
150
http://www.w3.org/International/questions/qa-apache-lang-neg for publishing
151
151
this on the web.
152
152
 
153
153
Testing
154
154
-------
155
155
 
156
 
We love automated testing! We added a couple of test cases to
157
 
 
158
 
    ./internals/tests/
159
 
 
160
 
and it would be great if you added more. We want to run these tests
 
156
We love automated testing! We added a couple of test cases to 
 
157
 
 
158
        ./internals/tests/
 
159
 
 
160
and it would be great if you added more. We want to run these tests 
161
161
whenever we build the package or publish the docs or whatever else. Just
162
162
to make sure that everything works fine. To run the test suite, run:
163
163
 
164
 
    make check
165
 
 
 
164
        make check
166
165
 
167
166
Functional (autopilot / selenium) tests
168
167
---------------------------------------
180
179
    autopilot3 list help_app
181
180
    autopilot3 run help_app
182
181
 
183
 
 
184
182
Debugging
185
183
---------
186
184
 
187
 
Did you find a bug and you're not sure how to debug it?
 
185
Did you find a bug and you're not sure how to debug it? 
188
186
 
189
187
Adding DEBUG=1 to the make command will give you additional information
190
 
in a few cases. For example will
 
188
in a few cases. For example will 
191
189
 
192
190
 - pelican print out debug information, which is very useful if you
193
191
   are changing pelican configuration options or are playing around
194
192
   with markdown extensions.
195
 
 - 'make launch' add the --inspector argument to ubuntu-html5-app-launcher.
196
 
   This will allow you to point your webkit-enabled browser to
197
 
    http://<yourip>:9221
 
193
 - 'make launch' add the --inspector argument to ubuntu-html5-app-launcher. 
 
194
   This will allow you to point your webkit-enabled browser to  
 
195
    http://<yourip>:9221  
198
196
   to examine some of the web attributes of the app.
199
 
 
 
197
  
200
198
 
201
199
Running the app on a phone
202
200
--------------------------
217
215
To file bugs, or view/submit merge proposals, simply use this project in
218
216
Launchpad:
219
217
 
220
 
    https://launchpad.net/help-app
 
218
        https://launchpad.net/help-app
221
219
 
222
220
To update the .pot file, simply run the following command in the top-level
223
221
directory:
224
222
 
225
 
    make update-pot
 
223
        make update-pot
226
224
 
227
225
If you want to get help with the app or anything else, ask the fine folks
228
226
in #ubuntu-app-devel - for example dholbach, balloons or dpm.