-
Notifications
You must be signed in to change notification settings - Fork 44
Bug 1019672 Add steps: pip, setup.py and running unit tests. #139
Changes from all commits
b6feaa2
454b061
a702022
a2d6769
c45d591
4abc89b
03f354c
240bae4
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,18 +1,26 @@ | ||
oneanddone | ||
========== | ||
|
||
The "One and Done" initiative, previously known as "QA Taskboard", is a workflow | ||
where Mozilla community contributors can pick tasks and work on them - one at a | ||
time, one day at a time - and feel good about doing them. | ||
|
||
One and Done is written with [Playdoh][playdoh] and [Django][django]. | ||
|
||
If you're interested in helping us out, please read through | ||
[the blog post][blogpost] and reach out to us! | ||
If you're interested in helping us out, please read through the | ||
[project wiki][wiki] and reach out to us! | ||
|
||
About the project: | ||
>Contribute to Mozilla QA - One task at a time, One day at a time. | ||
> | ||
>One and Done gives users a wide variety of ways to contribute to Mozilla. | ||
>You can pick an easy task that only takes a few minutes - or take on a | ||
>bigger challenge. This includes working on manual testing, automation, bug | ||
>verification, mobile testing and more. Tasks are from all QA teams - so you | ||
>can get involved with Automation, Firefox OS, Desktop Firefox, Mozilla | ||
>websites, Services, or Thunderbird. | ||
|
||
[django]: http://www.djangoproject.com/ | ||
[playdoh]: https://github.com/mozilla/playdoh | ||
[blogpost]: https://quality.mozilla.org/2013/10/qa-taskboard-development-call-for-participation/ | ||
[wiki]: https://wiki.mozilla.org/QA/OneandDone | ||
[persona]: https://developer.mozilla.org/Persona/The_implementor_s_guide/Testing | ||
[django-browserid]: https://github.com/mozilla/django-browserid | ||
|
||
|
||
Development Setup | ||
|
@@ -39,46 +47,73 @@ you don't have `pip` installed, you can install it with `easy_install pip`. | |
$ source venv/bin/activate | ||
``` | ||
|
||
3. Install the compiled requirements: | ||
3. Set up MySQL locally. The [MySQL Installation Documentation][mysql] explains how to do this. | ||
|
||
|
||
4. Create the initial empty database; make sure it's utf8: | ||
``` | ||
# Start the MySQL server | ||
$ mysql.server start | ||
# Once successfully started, log into the console | ||
# using your username and password | ||
$ mysql -uroot -p | ||
``` | ||
In the mysql console: | ||
```mysql | ||
CREATE DATABASE oneanddone | ||
DEFAULT CHARACTER SET utf8 | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Semicolon. |
||
DEFAULT COLLATE utf8_general_ci; | ||
``` | ||
To run all parts of the application, you will eventually need to populate this empty database with some example data, especially Tasks. There are many ways to populate the database. The method you choose may depend on the kind of data you want to add. | ||
* Use the create/edit features of your local One and Done instance. For example sign in with an administrator account and go to the `/tasks/create/` URL of the app to create Tasks. | ||
* Use the Django admin section of your local One and Done instance by going to the `/admin` URL -- this also relies on an admin account. You can define Task Teams here, for example. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. My change still mentions the Django admin even though it cannot be used for Tasks. I'm trying to make it clear that it might be useful for other db modifications. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Fair enough. |
||
* Use an external tool like MySQL Workbench. | ||
* Ask another active developer for a mysqldump of their local database. | ||
5. Install the compiled and development requirements: | ||
```sh | ||
$ pip install -r requirements/compiled.txt | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I tried running through the instructions from scratch, to verify if they work and to check on that
Is this something you can look into, @mjzffr? There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Actually, I just figured it out myself (thanks Google). Based on a blog post [1], I added an environment variable to the beginning of the pip command, so my full command line is:
I think we should add a note to the readme to do this if that error is encountered. [1] http://kaspermunck.github.io/2014/03/fixing-clang-error/ |
||
$ pip install -r requirements/dev.txt | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. The packages here are specifically aimed for developer version as mentioned here [0] There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Not sure what you mean, @bitgeeky. These instructions are for a development setup so I don't think it's necessary to further clarify that dev.txt refers to packages useful to developers. |
||
``` | ||
_Note_: On OS X (in particular 10.8.5, Xcode 5.1), you may encounter the following error: `clang: error: unknown argument. '-mno-fused-madd'`. Try running pip with the `ARCHFLAGS` environment variable set, as follows: `ARCHFLAGS=-Wno-error=unused-command-line-argument-hard-error-in-future pip install -r requirements/compiled.txt` | ||
|
||
4. Set up a local MySQL database. The [MySQL Installation Documentation][mysql] | ||
explains how to do this. Make sure your DB is utf8. | ||
|
||
5. Configure your local settings by copying `oneanddone/settings/local.py-dist` to | ||
6. Configure your local settings by copying `oneanddone/settings/local.py-dist` to | ||
`oneanddone/settings/local.py` and customizing the settings in it: | ||
|
||
```sh | ||
$ cp oneanddone/settings/local.py-dist oneanddone/settings/local.py | ||
``` | ||
|
||
The file is commented to explain what each setting does and how to customize | ||
them. One item in the local.py settings file you are going to want to change, if | ||
you are running this locally and not over HTTPS, is the following. | ||
|
||
Open up local.py, find and uncomment SESSION_COOKIE_SECURE = False | ||
|
||
them. Here are some highlights: | ||
* If you are running this locally and not over HTTPS, uncomment `SESSION_COOKIE_SECURE = False` | ||
* The `HMAC_KEYS` dictionary should not be empty. | ||
* Provide a value for `SECRET_KEY`. | ||
|
||
7. Create the initial empty database: | ||
|
||
7. Initialize your database structure: | ||
```sh | ||
# Start the MySQL server | ||
$ mysql.server start | ||
# Once successfully started, log into the console | ||
# using your username and password | ||
$ mysql -uroot -p | ||
# Create the database | ||
mysql> create database oneanddone; | ||
$ python manage.py syncdb | ||
``` | ||
If you are asked to create a superuser, do so. Don't worry if you miss this step: see the [Users](#users) section below for more information. | ||
|
||
8. Initialize your database structure: | ||
Once finished, the `syncdb` command should produce a message about which models have been synced. At the bottom, the message will include something like this: | ||
|
||
```sh | ||
$ python manage.py syncdb | ||
``` | ||
Not synced (use migrations): | ||
- oneanddone.tasks | ||
- oneanddone.users | ||
- rest_framework.authtoken | ||
``` | ||
|
||
This means that you must also run `./manage.py migrate [model]` for each model that is not synced with `syncdb`. More information about South migrations is included under the [Applying Migrations](#applying-migrations) section below. | ||
|
||
Users | ||
----- | ||
|
||
Playdoh uses [BrowserID][django-browserid], a.k.a. Mozilla Persona, for user authentication. To add users to your local database, simply sign into your local One and Done instance. You may want to use dummy email accounts as described in Mozilla's guide to [testing Persona][persona]. | ||
|
||
You need at least one superuser to be able to develop and test administrative features of the project. You can create as many superusers as you like with `python manage.py createsuperuser`. After that, sign into your local One and Done instance with the superuser's email address as usual. | ||
|
||
|
||
Applying Migrations | ||
------------------- | ||
|
@@ -90,22 +125,24 @@ run the following: | |
$ ./manage.py migrate oneanddone.tasks && ./manage.py migrate oneanddone.users | ||
``` | ||
|
||
If you make changes to an existing model you will need to regeneratre the schema migration as follows: | ||
If you make changes to an existing model, say `oneanddone.tasks`, you will need to regeneratre the schema migration as follows: | ||
|
||
```sh | ||
$ ./manage.py schemamigration oneanddone.tasks --auto | ||
``` | ||
|
||
To generate a blank schema migration: | ||
To generate a blank data migration: | ||
|
||
```sh | ||
$ ./manage.py datamigration oneanddone.mymodel data_migration_name | ||
# ./manage.py datamigration [model] [data_migration_name] | ||
# Example: | ||
$ ./manage.py datamigration oneanddone.tasks task_data | ||
``` | ||
|
||
Then fill in the generated file with logic, fixtures, etc. You can then apply this migration as above with: | ||
|
||
```sh | ||
$ ./manage.py migrate oneanddone.mymodel | ||
$ ./manage.py migrate oneanddone.tasks | ||
``` | ||
|
||
|
||
|
@@ -124,8 +161,21 @@ You can launch the development server like so: | |
$ python manage.py runserver | ||
``` | ||
|
||
If you are asked to create a super user, just enter no and let the process complete. | ||
Running Unit Tests | ||
------------------ | ||
You can run all the unit tests in verbose mode as follows: | ||
|
||
```sh | ||
$ python manage.py test -v 2 | ||
``` | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. This is a good point. Please also add a command to run a particular test or tests in a particular module. |
||
You can also run spefic tests: | ||
```sh | ||
# All tests in tasks/tests/test_helpers module. | ||
$ python manage.py test oneanddone.tasks.tests.test_helpers -v 2 | ||
# Just one test (PageUrlTests.test_basic) | ||
$ python manage.py test oneanddone.tasks.tests.test_helpers:PageUrlTests.test_basic -v 2 | ||
|
||
``` | ||
|
||
REST API Support | ||
---------------- | ||
|
@@ -169,7 +219,5 @@ Functional (Selenium) tests for oneanddone are maintained by the Web QA team and | |
|
||
License | ||
------- | ||
This software is licensed under the `Mozilla Public License v. 2.0`_. For more | ||
This software is licensed under the [Mozilla Public License v. 2.0](http://mozilla.org/MPL/2.0/). For more | ||
information, read the file ``LICENSE``. | ||
|
||
.. _Mozilla Public License v. 2.0: http://mozilla.org/MPL/2.0/ |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Add the much needed semicolons.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
That's all one command, only one semi-colon is needed at the very end.