This is a complete rewrite of the ACMx Labs website in Django 1.7. If you want to work on it, please read through the information below, then dive in! If you get stuck at any point, don't hesitate to contact us and ask questions.
How to Contribute
Before you can start working on ACMx Labs, there are a few initial setup steps you'll have to complete.
- Make sure you have accounts on GitHub and Trello, and ask to be added to the ACMx organizations on each.
- Install and configure
giton your computer. If you're using Windows, try GitHub for Windows; Mac users try GitHub for Mac.
- Windows and Mac users, read this; Linux users, read this.
- Learn how to use git and Django.
If you have a Windows or Mac machine, you will probably want to work from a
local clone, then deploy to a test server to see your changes. To get
started, clone the acmw_website repo through the GitHub program, or from the
git clone https://github.com/ColoradoSchoolOfMines/acmx_website.git.
Let me know that you're working from a Windows or Mac and need a test server, and I'll help you get set up with one.
Make whatever changes you want (see using git for an example
workflow, or use the GitHub program to manage your changes). Before pushing
to GitHub, deploy to the test server with
fab deploy and make sure
If you want to try installing Django locally instead of deploying to a test server, this page from the Test Driven Development with Python book might be helpful.
If you have a Linux machine you can use as a dev server, awesome. If you don't, but you want to try working on a server, just let me know and I'll get you set up with remote SSH access on one of mine. The instructions below assume you're working on a Debian-based server (like Ubuntu).
First, install and configure the tools you'll be using:
sudo apt-get update && sudo apt-get upgrade sudo apt-get install python-dev git build-essential python-pip sudo pip install virtualenvwrapper cat << EOF >> ~/.bashrc export WORKON_HOME=$HOME/.virtualenvs source /usr/local/bin/virtualenvwrapper.sh EOF source ~/.bashrc
Be sure to set up git.
Next, set up a virtualenv and grab everything you'll need to work on the website:
mkvirtualenv acmx git clone https://github.com/ColoradoSchoolOfMines/acmx_website.git cd acmx_website wget https://gist.githubusercontent.com/rshipp/51ec5a69070e37b8bd4a/raw/3eaa22ac686c3ec7268c5c9982e679d75e90cb11/secrets.py -O acmx_website/secrets.py wget https://gist.githubusercontent.com/rshipp/51ec5a69070e37b8bd4a/raw/c9ebfd5db795bad16d7f7898ac6f94566cd3882a/deployment.py -O acmx_website/deployment.py pip install -r requirements.txt
Finally, apply the database migrations and start up the Django development server with:
./manage.py syncdb ./manage.py runserver
When you're working on a remote server like this, you won't be able to use any
IDE or fancy graphical text editor. I highly recommend you learn how to use
vim, but since it has a bit of a learning curve, you may want to start out
nano instead. Just open files with
vim myfile.html or
Whenever you log into the server, you'll need to first "source" the virtualenv, with:
Then change to the website directory (
cd acmx_website), make sure you have
the latest code (
git pull), and start hacking.
Git is an awesome tool for collaborative development, but it takes some getting used to if you've never seen it before. GitHub has a great online tutorial for getting started with git, that will only take a few minutes.
For the most part, your development cycle should look something like this:
Pull in the latest code from GitHub:
Work on whatever new feature or bugfix you're adding. When you're done, add your changes:
git add -p
-p option brings up interactive add; press
y if the changes look
n if they don't and you want to go back and fix something. You
can also use
q to exit. Once everything looks right and you've added all
the changes, commit them:
(Note: If you added new files instead of just changing ones that were
already there, you should run
git add -A at this point.)
git commit -m "Change X to make it better"
And push the changes to GitHub:
If there are errors at this point, someone may have pushed their changes while you were making yours. Pull again, fix any merge conflicts, and push:
git pull git push
Working with Django
Since Django is a Python framework, all the logic for the site is written in Python. The models, which describe the database layout, are in projects/models.py. The views, which tell Django how to display different pages on the site, are in projects/views.py. These are the files backend developers will work with most.
If you change the models, you'll need to create a "migration" for your
changes. In Django 1.7, this is as easy as running
Windows and Mac users won't be able to do this without having Django
installed, so either do it on a Linux server, or ask for help from someone
To deploy changes to acmxlabs.org, you'll need an account on the server that has been added to the correct group. Ask someone to set up an account for you, then:
git remote add deploy ssh://email@example.com/git/acmx_deploy.git git push deploy master
If the changes don't show up, try Ctrl-Shift-R. If they still don't show up, you may need to reload the services on the server:
sudo service gunicorn reload sudo service nginx reload