Draft Version¶

Long before a piece of software is ready for testing, a "demo" or "proof of concept" or "rapid prototype" version is often created. This version demonstrates the user interface and basic functionality, but in a very limited version. For example, a "search" feature might not be implemented at all, but a "canned" search term can be entered and the software will show "canned" results.

This demo version allows the client to decide whether the interface is convenient, helpful and intuitive. It also helps the designers get a handle on what kinds of data will be available at different times, so that tables, queries, inserts and the like can be considered and nailed down more precisely than they were in the design phase.

For the purposes of this project, the draft version is the first release of your own project, as described in your plan. The emphasis should be on the interface: what pages you will have, how they will be connected, what forms you'll have, and so forth, even if they have to be "mock" versions at first. Note that the software must actually work; it can't be vaporware.

Core Features¶

This project phase falls roughly one third of the way through the time we have for coding the project, so you'll also want to have made some progress on that front. So, in addition to having the basics of the interface worked out, you'll want to have implemented some (not all) of your core features. (You'll want to have all or most of the core features implemented by the in-class project presentations, reserving the bells and whistles for exam week.) You can decide what you want to attack first, but it often makes sense to implement adding data before you implement searching the data, so that you can use your software to put in your test data. Some people like to start with logins and session management; others prefer to defer that in favor of the main site content. This is your choice, but you should think about how to manage your time during the project and make sure you get enough done by this milestone, so that the next phase is not too grueling.

How to Submit it¶

It's sufficient for me to have access to the team account so that I can run your code. Make sure there is a clear directory for me to grade that no one on the team will touch while grading is proceeding. Call the directory draft.

How to Use your Team Account¶

When you created your team account, whoever did that specified the username and password. For the sake of this description, let's suppose that they were

username: team_awesome
password: correct horse battery staple

Any member of the team can use those credentials to login to your team account. When VS code prompts you for user@host you can specify team_awesome@cs.wellesley.edu. VS Code will then prompt you for the password, which you can type in. This is just like the beginning of the semester, before you learned about SSH keys.

Any member of the team can also copy their personal public key to the team account, if they want to skip the password in the future. That would be done the same as we did earlier, but copying to a different account. So, on your laptop (not via VS Code), you would do:

ssh-copy-id team_awesome@cs.wellesley.edu

The ssh-copy-id command will ask you for your password, and then it will add your public key to the ~/.ssh/authorized_keys file in the team account. Then you won't be asked for a password when you login from your laptop to the team account. Each team member can each do that if they want, so the team account's authorized_keys files could have 3-4 public keys in it.

Once you are logged into the team account, you can set up a virtual environment and download a copy of the code from Github, into a folder called draft. Team members can continue to work in their own accounts, leaving the draft version in the team account as a frozen snapshot of that version of the project. I'll grade that snapshot.

This might seem like a lot, but much of it is quick to do:

• a few minutes to login, either with a password or SSH key
• a few minutes to set up the virtual environment (though if you've forgotten how, see the next section)
• a few minutes to create a folder and git clone the code from Github.

Setting up the Virtual Environment¶

We've set up a virtual environment before, but that was over a month ago. Here are the details of setting up a CS 304 virtual environment.

If you've installed additional python modules, you might need to modify those instructions.

Here is a quick summary of commands for setting up a CS 304 venv for your team account:

python 3.9 -m venv venv         # creates virtual environment folder
source venv/bin/activate
pip install --upgrade pip
pip install flask
pip install pymysql
pip install bcrypt
~cs304flask/pub/bin/install-cs304dbi

You can pip install any additional packages you might need.

What to turn in¶

I will need some help in grading these, since everyone is doing something slightly or radically different. Therefore, the Google doc needs to describe:

• Briefly remind me what the project is about.
• The account and directory with the your code to run/grade.
• The URLs of the web pages I need to look at or test, if it's not obvious and you don't yet have a menu bar.
• The sample usernames, items, and other inputs, so I can use the forms.
• Directions on how to use your pages. That means telling me where to click, what data to enter, what usernames/passwords I need, and so forth. It's amazing how dumb I can be with someone's web app, so be really clear here.

Just try to put yourself in my shoes when I'm looking at your app. You don't want me to think it's broken or missing something when I'm just not using it correctly or have overlooked something.

The title of the document is very important, otherwise I will mis-place it and lose time finding it. The title of the document will be CS304-SEM-YYYY-draft-TEAM where the SEM is the semester (Fall/Spring), the the YYYY is year, and the TEAM is name of your project or team account or your names.

Since Google often makes these documents hard to find (weird for a search company...), please submit the URL via this

URL submission Google Form

Code Upload¶

I also want to comment on your code. I now think the Gradescope programming assignment works well. I've created a "P3 Project Draft Programming Assignment." Please zip your code and upload the zip file to Gradescope.

Pruning the Zip File¶

The zip file for your project folder may well be enormous, and it is worthwhile, and easy, to make it much slimmer. Let's first see why it's enormous and then how to prune it.

The project folder might look like this:

draft/
    .git/
    app.py
    events.py
    logins.py
    db-setup.sql
    __pycache__
    templates/
        home.html
        ...
    static/
        ...

Most of those are files you worked on and need to submit. But the .git/ folder (which will not show up on an ordinary ls command, because it starts with a dot) is where all your git commits live. That folder is often enormous. And there's no reason to submit it. Similarly, the __pycache__ folder is not needed as well.

So, how to prune this? Do not delete the .git folder; git needs that! But here's what we will do:

1. copy the project folder
2. prune .git and __pycache__ from the copy
3. zip the copy
4. delete the copy

For the sake of example, suppose we name the copy tmp. Here are the commands you need. Edit them as you see fit

cp -r draft tmp
rm -r tmp/.git
rm -r tmp/__pycache__
zip -r tmp.zip tmp
rm -r tmp

When I helped a team do that, the pruned zip file was only 2% of the size of the original zip file!

How I will test == How you should test¶

Just to be clear, here's how I will test your code:

• I will login to your team account.¹
• I will activate the venv that is in your team account
• I will cd to your draft directory. ²
• I will run your app.py
• I will test your app in the browser, using the directions that you gave me in the Google Doc.
• I will review and comment on the code using Gradescope.

Grading¶

Your draft version should have:

1. Most of the UI figured out (pages, menus, etc)
2. Some core functions working. Note that "core functions" means something the web app does, not a Python function. Furthermore, your web app is a database with a web interface, so the core functions are all database operations, like insert, updating, searching, and so forth. (Think about homeworks 3, 4, and 5).
3. No vulnerabilities (SQL injection, XSS)
4. Good documentation and modularity

Also, this is very important: separate your code for each phase: have a separate place (folder) for your draft version, another for your alpha version and so forth.

Final Checklist¶

Make sure you have done all this:

1. Tested/run the code in your team account that I will be running
   • it should have a working venv
   • it should have all the necessary code in a clearly marked folder (e.g. draft)
2. Created a Google Doc of directions and other information and submitted it via the URL submission Google form, above
   • Make sure I can view this file. You will need to share it with me
3. Uploaded a zip file of your code to Gradescope.
   • there is only one code submission per team
   • one person uploads the zip file and lists all team members on the group submission