Add the mission statement here

Student Growth Tracker is an enhanced gradebook application that allows educators to track and monitor students' progress with respect to the Common Core standards.

Student Growth Tracker is a web2py application.

• Lawrence Graves
• Allan Guan
• Bryan Patzke
• Joesph Richard

This is a brief tutorial on how to set up your environment to work on the Student Growth Tracker project.

• git (if you don't have it) Make sure it has the command-line tools.
• git flow (On Mac you can install with MacPorts, or another package manager.)
• Download and install python (probably just a link to the documentation)
• Using pip
• What to install with pip (before you set up your virtual environment)
  • virtualenv
  • virtualenvwrapper (-win for windows)
• Set up your virtual environment.
• What to install with pip (after you set up your virtual environment)
  • pyDAL
  • sphinx
  • sphinx-bootstrap-theme
• web2py (if you clone the github repository, delete the git stuff)

These are the tools you'll need to work on web2py applications. The list isn't comprehensive, but it will give you what you need to get started.

• Python (version 2.x - the latest is Python 2.7.10)¹
• git
• git-flow
• web2py²

Once you get Python, git, and git-flow installed, You'll need to install a few extra pieces -- some to make your life easier, and some for the project.

Pip is a package manager for Python. If you need something that doesn't come with Python, you'll use pip to install it. To make sure you have pip installed, just type the following at the command prompt: :

$ pip --version
pip 7.1.0 from /path/to/pip/directory (python 2.7)

You should see something like the second line. If you get an error, you can download pip from pypi.

Before we install the packages we'll need for the project, you should install the virtualenv and virtualenvwrapper (the Windows version is called virtuaenvwrapper-win) packages with pip. :

$ pip install virtualenv
<lots of install information>

$ pip install virtualenvwrapper
<lots of install information>

Virtual environment -- as the name implies -- allows you to set up isolated Python environments, each with its own set of packages installed. The documentation for virtualenv can give you all the gory details, but it's probably best to leave that for another time.

Virtual environment wrapper hides the sometimes messy details of working with virtualenv behind a much nicer user interface. Both virtualenvwrapper and virtualenvwrapper-win have good introductions, so your best bet for getting started is to follow the appropriate link for your version.

Now we can set up a virtual environment for working on the project. I chose to call my virtual environment capstone as it's descriptive enough and short. It doesn't matter what you name it -- we don't all have to use the same name as the virtual environment is strictly a local tool -- so choose a name that you'll remember. Since web2py requires python2, we need to make sure that our virtualenv uses python2 instead of python3. To create the capstone environment, type:

$ mkvirtualenv -p /path/to/python2 capstone

OR:

$ mkvirtualenv --python=/path/to/python2 capstone
...
<lots of output>

If python2 is the default version of python -- or the only version -- then you don't need to specify it in the mkvirtualenv command.

Once you issue the command, your prompt should look something like this:

(capstone) $ _

The (capstone) prefix on your prompt tells you what environment you're using at the moment. To exit the virtual environment, just type:

(capstone) $ deactivate

To work in the capstone environment, type:

$ workon capstone

Working with virtual environments takes some getting used to, but ultimately it can save the time wasted on chasing bugs related to library versions, and other dependency issues. Essentially, it lets you freeze your python environment to protect it from interference.

There are only a few more things that need to be installed so we can get started. You'll use pip to install all of them. Don't forget to make sure that you have your virtualenv activated -- as indicated by the (env-name) tag in front of your command prompt. If it's not, just use the workon env-name command to activate the environment.

pyDAL is the Python Database Abstraction Layer. pyDAL makes the web2py framework database agnostic. It provides an object-oriented framework for building and working with your data models. It transparently transforms your method calls into database commands, and returns results as python objects.

To install pyDAL, type:

(capstone) $ pip install pyDAL

Sphinx is a documentation tool that makes creating documentation nearly effortless. As long as your code has docstrings -- they're the python version of java doc comments -- for all of your public interface items, Sphinx can use them to build the documentation for the project automatically. It can also run tests and check the documentation coverage of your code.

To install sphinx, type:

(capstone) $ pip install pyDAL

While this isn't strictly necessary, this theme provides support for the bootstrap UI framework. This is important since web2py uses bootstrap as well, which means we'll have a consistent user interface between the application and the documentation.

To install sphinx-bootstrap-theme, type:

(capstone) $ pip install pyDAL

Once you've downloaded the source version of web2py³, unzip it to a convenient location. Poke around a little bit to see what's what. Almost all of the built-in functionality of the framework is in the gluon[3] directory. We won't ever have to touch anything in the gluon directory.

All of our code will go into a subdirectory of the applications directory named student-growth-tracker. This will also be the root of your git repository, but we'll get to that shortly. To start web2py, all you have to do is type:

/path/to/web2py $ python web2py.py

Enter an admin password -- it's only used for this session, so feel free to make it something really simple -- and -- if your browser doesn't open the Welcome application automatically -- open your favorite browser and go to http://127.0.0.1:8000.

The overview chapter in the web2py documentation provides a good introduction to working with web2py. It covers what I did here, but in more detail. It also walks you through creating a basic application, and working with some of the features of the framework. I suggest you go through this introduction before moving on with the rest of the setup.

You're almost ready to start working on the application, but you have a few final steps first.

You should make a fork of the master repository in your personal account. All you need to do is go to the project page and click the Fork button on the right-hand side, near the top of the page. Github will show you an animation while it copies things over, and then you'll be take to your own shiny new copy of the student-growth-tracker repository.

You need to clone your Github repository to your local system. First, navigate to the web2py/applications directory. Then, type:

(capstone) $ git clone https://github.com/<username>/student-growth-tracker.git

Where <username> is your Github user name. You should see something like:

Cloning into 'student-growth-tracker'...
remote: Counting objects: 115, done.
remote: Compressing objects: 100% (92/92), done.
Receiving objects:  85% (98/115)
Receiving objects: 100% (115/115), 998.58 KiB | 0 bytes/s, done.
Resolving deltas: 100% (16/16), done.
Checking connectivity... done.

You should now have a directory named student-growth-tracker in your applications directory.

If you start web2py, the application should be ready for use. You'll have to go to the admin interface, or go to http://127.0.0.1:8000/student-growth-tracker.

You all have this installed. Ping me if you have any questions.

1. Log into your Github account.
2. Navigate to the master repository
3. In the upper right-hand corner of the screen, click the "Fork" button.
4. Wait while Github copies the repository to your account.

You should now have a copy of the master repository in your Github account.

I'll give you the command-line version. If you're using a graphical tool, the documentation should tell you how to clone a repository.

1. Navigate to the applications directory in your web2py directory. For example, my web2py directory is in /Users/bpatzke/school/capstone/student-growth-tracker/. so I would go to /Users/bpatzke/school/capstone/student-growth-tracker/web2py/applications/.

2. The command to clone your repository is:

   $ git clone https://github.com/<github-user-name>/student-growth-tracker.git
   Cloning into './student-growth-tracker'...
   remote: Counting objects: 131, done.
   remote: Compressing objects: 100% (106/106), done.
   Receiving objects:  84% (111/131)
   Receiving objects: 100% (131/131), 1003.71 KiB | 0 bytes/s, done.
   Resolving deltas: 100% (25/25), done.
   Checking connectivity... done.

   where <github-user-name> is your Github user name.

Et, voilà! You have your own working copy of the project!

I need to say a bit about branching. Git makes branching very easy. That's why I prefer it. Branching is important because it allows you to experiment without worrying about whether you're going to screw up your code base. If you want to try something, create a branch and start coding. If things go horribly wrong, just delete the branch. No harm done.

You have to have at least one branch, traditionally called master in git. Your master branch is the one you really want to be careful with. Just like the master repository, your master branch is where you'll merge your local changes when you're ready to submit your changes to the master repository.

To make managing branches easier, we're going to use git-flow. I suggest you read the brief introduction on the git-flow Github page. That should give you enough information to get started.

To install git-flow on Windows, I suggest the GitHub for Windows option.

To install git-flow on OS X, I suggest the MacPorts option.

Now for some practice using git and git-flow. If you haven't already, you should l_clone_to_local.

Initializing git-flow is very simple.

1. Open a command/terminal window and navigate to your project directory.

2. Type the following, and just accept all of the defaults:

   $ git flow init
   
   Which branch should be used for bringing forth production releases?
      - master
   Branch name for production releases: [master]
   Branch name for "next release" development: [develop]
   
   How to name your supporting branch prefixes?
   Feature branches? [feature/]
   Release branches? [release/]
   Hotfix branches? [hotfix/]
   Support branches? [support/]
   Version tag prefix? []
   
   $ _

If you use the git status command, you'll see that you're now on the develop branch. I tend to do all of my work in feature branches, and then merge those into the develop branch. I use the develop branch as a second master branch, of sorts. An example should help clarifiy things.

Create a feature branch so you can update the README.rst file with a link to your Github account.:

$ git flow feature start update-readme
Switched to a new branch 'feature/update-readme'

Summary of actions:
- A new branch 'feature/update-readme' was created, based on 'develop'
- You are now on branch 'feature/update-readme'

Now, start committing on your feature. When done, use:

     git flow feature finish update-readme

$ _

Git-flow always tells you what it's doing, and provides helpful hints to keep you on track.

Using your favorite text editor/IDE, edit the Authors section of README.rst to create a link to your Github account. You can just copy what I did with my name. Save your changes and exit the application.

Back in the command/terminal window, type git status. You should see something like the following:

On branch feature/update-readme
Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git checkout -- <file>..." to discard changes in working directory)

      modified:   README.rst

no changes added to commit (use "git add" and/or "git commit -a")

There are three states a modified file can be in: unstaged, staged and committed. Right now, we've updated README.rst, but haven't told git that we want to keep those changes. To stage the changes, use the git add command.:

$ git add README.rst

Git status now shows that the changes to README.rst are staged, and ready to be committed.:

On branch feature/update-readme
Changes to be committed:
  (use "git reset HEAD <file>..." to unstage)

      modified:   README.rst

It even tells you how to remove your changes from staging.

Now we commit the changes to write them to our local copy of the repository.:

$ git commit -m "Updating README.rst with a link to my Github account."  README.rst
[feature/update-readme 54cea0d] Updating README.rst with a link to my Github account.
 1 file changed, 1 insertion(+), 1 deletion(-)

Depending on the changes you made, the last line might be different.

You'll realize by now, of course, that all of these steps for such a tiny change is overkill, but when we're done, you'll have done almost everything you'll need to do to use git for this project.

Our changes are now committed to the feature/update-readme branch. Now we need to merge them back into the other branches.:

$ git flow feature finish update-readme
Switched to branch 'develop'
Your branch is up-to-date with 'origin/develop'.
Updating fc5f1c4..54cea0d
Fast-forward
 README.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
Deleted branch feature/update-readme (was 54cea0d).

Summary of actions:
- The feature branch 'feature/update-readme' was merged into 'develop'
- Feature branch 'feature/update-readme' has been removed
- You are now on branch 'develop'

As usual, git-flow tells you exactly what it's done, and where you've ended up.

On really nice thing about git-flow is that it doesn't interfere with any of the standard git commands. This update doesn't warrant a full release, so we're going to practice using git without the aid of git-flow.

You should be on the develop branch now. To merge your updates into your master branch, you need be on your master branch. Generally, merging is a straightforward process. Use the following commands to merge the develop branch into the master branch.:

$ git checkout master
Switched to branch 'master'
Your branch is up-to-date with 'origin/master'.

$ git merge develop
Merge made by the 'recursive' strategy.
 README.rst          |  2 +-
 1 files changed, 2 insertions(+), 2 deletions(-)

If you do a git status now, you'll see that your remote repository is out of date.:

$ git status
On branch master
Your branch is ahead of 'origin/master' by 1 commit.
  (use "git push" to publish your local commits)
nothing to commit, working directory clean

As the message says, you can push your changes to your remote repository with the git push command. It will prompt you for your username (actually, the email address you used to sign up for Github) and password. Then it will print a bunch of information to the screen. If it tells you the push was successful, you're good to go.

The home stretch

To create a pull request, you'll need to long into your Github account. Go to your student-growth-tracker repository. You should see a button that says, "Create Pull Request" (or something similar). Click the button, and follow the directions to create the pull request.

Now it's just a question of waiting for your pull request to be merged into the master repository.

Footnotes