Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Loading…

Bug 1019672 Add steps: pip, setup.py and running unit tests. #139

Merged
merged 8 commits into from

3 participants

@mjzffr

@bitgeeky r? If everything looks ok to you, we can run it by Bob.

README.md
((10 lines not shown))
```
-4. Set up a local MySQL database. The [MySQL Installation Documentation][mysql]
+4. Deploy the project in "development" mode:
+
+ ```sh
+ $ python setup.py develop

I don't see much of code that installs any packages here [0]
We already install packages using pip, I am not sure if we really need it. Do you have any reason to add this @mjzffr ?
[0] https://github.com/mozilla/oneanddone/blob/master/setup.py

@mjzffr
mjzffr added a note

I thought this was necessary to run the tests because it makes the oneanddone package importable. @bobsilverberg suggested it when I was having trouble running the tests a couple of weeks ago. However, I set up the project again without this and it doesn't seem necessary after all. I'm ok with removing it, but maybe Bob has some reason to keep it?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
README.md
((6 lines not shown))
```sh
$ pip install -r requirements/compiled.txt
+ $ pip install -r requirements/dev.txt

The packages here are specifically aimed for developer version as mentioned here [0]
We can mention it here if we want to add this.
[0] https://github.com/mozilla/oneanddone/blob/master/requirements/dev.txt#L1

@mjzffr
mjzffr added a note

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
README.md
@@ -126,6 +133,13 @@ $ 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 the unit tests in verbose mode as follows:
+
+```sh
+$ python manage.py test -v 2
+```

This is a good point. Please also add a command to run a particular test or tests in a particular module.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@bitgeeky

@mjzffr I added some comments. Let me know when its ready so that we can ask Bob for a review.

@bitgeeky bitgeeky commented on the diff
README.md
@@ -39,16 +39,40 @@ 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
@bitgeeky
bitgeeky added a note

Add the much needed semicolons.

@mjzffr
mjzffr added a note

That's all one command, only one semi-colon is needed at the very end.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@bitgeeky bitgeeky commented on the diff
README.md
((4 lines not shown))
-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
@bitgeeky
bitgeeky added a note

Semicolon.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
README.md
((8 lines not shown))
+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
+ 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.
+
@bitgeeky
bitgeeky added a note

This line sounds a bit ambiguous. Mention how to populate the data, is it using mysql cli or the admin panel after the application is installed.

@bobsilverberg Owner

I agree that if we're going to tell people they will need to add tasks, we should tell them how. Mention that they can do it via the Task Admin menu after logging in as an administrator.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
README.md
((25 lines not shown))
```sh
$ pip install -r requirements/compiled.txt
+ $ pip install -r requirements/dev.txt
+ ```
+
+6. Deploy the project in "development" mode:
+
+ ```sh
+ $ python setup.py develop
@bitgeeky
bitgeeky added a note

If Bob asked you to run this command he would have had some reason. I will leave this here for now, may be he can comment in his review about this.

@bobsilverberg Owner

I don't fully understand how all this setup stuff works, but I assumed that, in order to actually "install" the app in the virtualenv, you need to call python setup.py develop. Have you both found that that is not necessary?

@mjzffr
mjzffr added a note

@bitgeeky Could you please try out the current build instructions and confirm that running setup.py is not needed?

@bobsilverberg Owner

After running through all of the steps it does seem like this step is not needed, so remove it.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
README.md
@@ -126,6 +143,21 @@ $ 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
+```
+You can also run spefic tests. Examples:
+```sh
+# All tests in test_helpers module.
+$ python ./manage.py test oneanddone.tasks.tests.test_helpers -v 2
@bitgeeky
bitgeeky added a note

manage.py is an executable in itself. Either just do ./manage.py or python manage.py

@mjzffr
mjzffr added a note

Yep, thanks for catching that!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@bitgeeky

r+ wc
Few small suggestions. Please fix them and directly ask Bob for a review.

@mjzffr

@bobsilverberg r? (Especially Line 71, setup.py)

README.md
@@ -126,6 +143,21 @@ $ python manage.py runserver
If you are asked to create a super user, just enter no and let the process complete.
@bobsilverberg Owner

I'm not sure why this line is here. I always create a super user. What happens if you do not create a super user? How are you able to access the admin part of the app?

@bobsilverberg Owner

Actually, I think this line is in the wrong place now too. I think it was meant to live with the part about running python manage.py syncdb, but I still think it's invalid.

@mjzffr
mjzffr added a note

Right and right. :)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
README.md
@@ -126,6 +143,21 @@ $ 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
+```
+You can also run spefic tests:
+```sh
+# All tests in test_helpers module.
@bobsilverberg Owner

Perhaps this should read All tests in /tasks/tests/test_helpers module.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@bobsilverberg

I have some other comments on the contents of the file, but Github won't allow me to comment on lines that are not close to lines that have been changed, so I'll put links to the lines in here:

https://github.com/mjzffr/oneanddone/blame/readme/README.md#L4: I think it should say workflow tool, instead of just workflow.

https://github.com/mjzffr/oneanddone/blame/readme/README.md#L116: This should read To generate a blank data migration. Also, instead of oneanddone.mymodel, which is confusing, perhaps it should indicate that mymodel is the model in question, i.e., tasks. I'm not sure of the best way of documenting that, but as it is I think it is confusing.

In fact, I really wouldn't expect a contributor to be creating a data migration anyway, so perhaps it would be best to just remove everything from https://github.com/mjzffr/oneanddone/blame/readme/README.md#L116 to https://github.com/mjzffr/oneanddone/blame/readme/README.md#L126.

@mjzffr

@bobsilverberg re "workflow": I just noticed that there's a request to replace that whole description (https://bugzilla.mozilla.org/show_bug.cgi?id=1030992)

@mjzffr

@bobsilverberg re migrations section: FWIW, those details about migrations helped me understand some otherwise mysterious commits early on, how the project is organized, etc. (even though I have yet to perform a migration myself). The section is already written; I wouldn't throw it away.

@bobsilverberg

Actually, Task admin has been removed from the standard django admin as it needed to be changed to deal with the new data model and we already have the functionality inside the tool.

README.md
((10 lines not shown))
+ # 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
+ 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 do this.
+ * 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
+
+ * 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.
@bobsilverberg Owner

Oops, I added my comment to the commit, not the PR diff, so I'm adding it here as well as it'll be easier to see and track:

Actually, Task admin has been removed from the standard django admin as it needed to be changed to deal with the new data model and we already have the functionality inside the tool.

@mjzffr
mjzffr added a note

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.

@bobsilverberg Owner

Fair enough.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@bobsilverberg

Looks good, @mjzffr. Just one change please.

README.md
((16 lines not shown))
+ In the mysql console:
+ ```mysql
+ CREATE DATABASE oneanddone
+ DEFAULT CHARACTER SET utf8
+ 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.
+
+ * 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
@bobsilverberg Owner

I tried running through the instructions from scratch, to verify if they work and to check on that setup.py requirement, and I found that I get an error when trying to run the above command. I am on OS X 10.8.5. I know I was able to get this installed in the past (as I have it all running locally now), but this concerns me as I imagine others might run into the same issue. The message from pip looks like this:

~/gitRepos/tmp/oneanddone[master*]$ pip install -r requirements/compiled.txt
Downloading/unpacking MySQL-python==1.2.3c1 (from -r requirements/../vendor/src/funfactory/funfactory/requirements/compiled.txt (line 1))
  Downloading MySQL-python-1.2.3c1.tar.gz (89kB): 89kB downloaded
  Running setup.py (path:/Users/bsilverberg/.virtualenvs/oneanddone-pr139/build/MySQL-python/setup.py) egg_info for package MySQL-python

Downloading/unpacking Jinja2==2.5.5 (from -r requirements/../vendor/src/funfactory/funfactory/requirements/compiled.txt (line 2))
  Downloading Jinja2-2.5.5.tar.gz (438kB): 438kB downloaded
  Running setup.py (path:/Users/bsilverberg/.virtualenvs/oneanddone-pr139/build/Jinja2/setup.py) egg_info for package Jinja2

    warning: no previously-included files matching '*' found under directory 'docs/_build'
    warning: no previously-included files matching '*.pyc' found under directory 'jinja2'
    warning: no previously-included files matching '*.pyc' found under directory 'docs'
    warning: no previously-included files matching '*.pyo' found under directory 'jinja2'
    warning: no previously-included files matching '*.pyo' found under directory 'docs'
Downloading/unpacking py-bcrypt==0.3 (from -r requirements/../vendor/src/funfactory/funfactory/requirements/compiled.txt (line 5))
  Downloading py-bcrypt-0.3.tar.gz
  Running setup.py (path:/Users/bsilverberg/.virtualenvs/oneanddone-pr139/build/py-bcrypt/setup.py) egg_info for package py-bcrypt

Installing collected packages: MySQL-python, Jinja2, py-bcrypt
  Running setup.py install for MySQL-python
    building '_mysql' extension
    clang -fno-strict-aliasing -fno-common -dynamic -g -Os -pipe -fno-common -fno-strict-aliasing -fwrapv -mno-fused-madd -DENABLE_DTRACE -DMACOSX -DNDEBUG -Wall -Wstrict-prototypes -Wshorten-64-to-32 -DNDEBUG -g -Os -Wall -Wstrict-prototypes -DENABLE_DTRACE -pipe -Dversion_info=(1,2,3,'gamma',1) -D__version__=1.2.3c1 -I/usr/local/mysql/include -I/System/Library/Frameworks/Python.framework/Versions/2.7/include/python2.7 -c _mysql.c -o build/temp.macosx-10.8-intel-2.7/_mysql.o -Os -g -fno-strict-aliasing -arch x86_64
    clang: error: unknown argument: '-mno-fused-madd' [-Wunused-command-line-argument-hard-error-in-future]
    clang: note: this will be a hard error (cannot be downgraded to a warning) in the future
    error: command 'clang' failed with exit status 1
    Complete output from command /Users/bsilverberg/.virtualenvs/oneanddone-pr139/bin/python -c "import setuptools, tokenize;__file__='/Users/bsilverberg/.virtualenvs/oneanddone-pr139/build/MySQL-python/setup.py';exec(compile(getattr(tokenize, 'open', open)(__file__).read().replace('\r\n', '\n'), __file__, 'exec'))" install --record /var/folders/sk/1kj23lvn46n7pvr7_xk074wm0000gn/T/pip-O1DeTX-record/install-record.txt --single-version-externally-managed --compile --install-headers /Users/bsilverberg/.virtualenvs/oneanddone-pr139/include/site/python2.7:
    running install

running build

running build_py

creating build

creating build/lib.macosx-10.8-intel-2.7

copying _mysql_exceptions.py -> build/lib.macosx-10.8-intel-2.7

creating build/lib.macosx-10.8-intel-2.7/MySQLdb

copying MySQLdb/__init__.py -> build/lib.macosx-10.8-intel-2.7/MySQLdb

copying MySQLdb/converters.py -> build/lib.macosx-10.8-intel-2.7/MySQLdb

copying MySQLdb/connections.py -> build/lib.macosx-10.8-intel-2.7/MySQLdb

copying MySQLdb/cursors.py -> build/lib.macosx-10.8-intel-2.7/MySQLdb

copying MySQLdb/release.py -> build/lib.macosx-10.8-intel-2.7/MySQLdb

copying MySQLdb/times.py -> build/lib.macosx-10.8-intel-2.7/MySQLdb

creating build/lib.macosx-10.8-intel-2.7/MySQLdb/constants

copying MySQLdb/constants/__init__.py -> build/lib.macosx-10.8-intel-2.7/MySQLdb/constants

copying MySQLdb/constants/CR.py -> build/lib.macosx-10.8-intel-2.7/MySQLdb/constants

copying MySQLdb/constants/FIELD_TYPE.py -> build/lib.macosx-10.8-intel-2.7/MySQLdb/constants

copying MySQLdb/constants/ER.py -> build/lib.macosx-10.8-intel-2.7/MySQLdb/constants

copying MySQLdb/constants/FLAG.py -> build/lib.macosx-10.8-intel-2.7/MySQLdb/constants

copying MySQLdb/constants/REFRESH.py -> build/lib.macosx-10.8-intel-2.7/MySQLdb/constants

copying MySQLdb/constants/CLIENT.py -> build/lib.macosx-10.8-intel-2.7/MySQLdb/constants

running build_ext

building '_mysql' extension

creating build/temp.macosx-10.8-intel-2.7

clang -fno-strict-aliasing -fno-common -dynamic -g -Os -pipe -fno-common -fno-strict-aliasing -fwrapv -mno-fused-madd -DENABLE_DTRACE -DMACOSX -DNDEBUG -Wall -Wstrict-prototypes -Wshorten-64-to-32 -DNDEBUG -g -Os -Wall -Wstrict-prototypes -DENABLE_DTRACE -pipe -Dversion_info=(1,2,3,'gamma',1) -D__version__=1.2.3c1 -I/usr/local/mysql/include -I/System/Library/Frameworks/Python.framework/Versions/2.7/include/python2.7 -c _mysql.c -o build/temp.macosx-10.8-intel-2.7/_mysql.o -Os -g -fno-strict-aliasing -arch x86_64

clang: error: unknown argument: '-mno-fused-madd' [-Wunused-command-line-argument-hard-error-in-future]

clang: note: this will be a hard error (cannot be downgraded to a warning) in the future

error: command 'clang' failed with exit status 1

----------------------------------------
Cleaning up...
Command /Users/bsilverberg/.virtualenvs/oneanddone-pr139/bin/python -c "import setuptools, tokenize;__file__='/Users/bsilverberg/.virtualenvs/oneanddone-pr139/build/MySQL-python/setup.py';exec(compile(getattr(tokenize, 'open', open)(__file__).read().replace('\r\n', '\n'), __file__, 'exec'))" install --record /var/folders/sk/1kj23lvn46n7pvr7_xk074wm0000gn/T/pip-O1DeTX-record/install-record.txt --single-version-externally-managed --compile --install-headers /Users/bsilverberg/.virtualenvs/oneanddone-pr139/include/site/python2.7 failed with error code 1 in /Users/bsilverberg/.virtualenvs/oneanddone-pr139/build/MySQL-python
Storing debug log for failure in /var/folders/sk/1kj23lvn46n7pvr7_xk074wm0000gn/T/tmpsJh6Ic

Is this something you can look into, @mjzffr?

@bobsilverberg Owner

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:

ARCHFLAGS=-Wno-error=unused-command-line-argument-hard-error-in-future pip install -r requirements/compiled.txt

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/

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
README.md
((46 lines not shown))
-5. Configure your local settings by copying `oneanddone/settings/local.py-dist` to
+7. Configure your local settings by copying `oneanddone/settings/local.py-dist` to
@bobsilverberg Owner

This section does not specifically call out the need to set both HMAC_KEYS and SECRET_KEY, and it's not entirely obvious from the file that you need to do that. If you don't, however, the rest of the instructions won't work, so I think it's worth calling those out here.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@bobsilverberg

Looks good @mjzffr. Thanks for doing this.

@bobsilverberg bobsilverberg merged commit b38bddc into from
@mjzffr mjzffr deleted the branch
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
This page is out of date. Refresh to see the latest.
Showing with 84 additions and 36 deletions.
  1. +84 −36 README.md
View
120 README.md
@@ -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,16 +47,36 @@ 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
@bitgeeky
bitgeeky added a note

Add the much needed semicolons.

@mjzffr
mjzffr added a note

That's all one command, only one semi-colon is needed at the very end.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
+ DEFAULT CHARACTER SET utf8
@bitgeeky
bitgeeky added a note

Semicolon.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
+ 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.
+ * 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
+ $ pip install -r requirements/dev.txt
```
+ _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
@@ -56,29 +84,36 @@ you don't have `pip` installed, you can install it with `easy_install pip`.
```
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
+```
+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/
Something went wrong with that request. Please try again.