This repository is for the code that comprises the Outreachy website.

What is Outreachy?

Outreachy provides internships in open source. Outreachy provides internships to anyone from any background who faces underrepresentation, systemic bias, or discrimination in the technical industry where they are living.

Outreachy internships are:

• 💵 Paid - $7,000 USD total internship stipend
• 🌍 Remote - both interns and mentors work remotely
• 🕰 3 months - internships run May to August, or December to March

Internships are not linked to employment opportunities at supporting organizations.

Technology used in Outreachy website

Commonly used technology

The Outreachy website is built with Python and a web framework called Django. If you are creating new dynamic web content, you'll become familiar with Django over time.

Django allows us to build HTML using the Django Templating Language. If you are editing static content, you will get familiar with the HTML templating language over time.

The Outreachy website uses the Bootstrap framework for CSS and UI elements. If you are working with CSS, JavaScript, or HTML layout, you'll get familiar with Bootstrap over time.

Less commonly used technology

There are a few pages that use jQuery. You should not need to learn jQuery unless you're working on that code.

The Outreachy website uses a content management system called Wagtail, which builds on top of Django. Wagtail is being depreciated from the Outreachy website, so you should not need to know much about it. What you do need to know is that Wagtail allows people to add static webpages and images to the Outreachy website.

Pages created and images uploaded to Wagtail do not become a part of this repository. Instead, the pages and images are stored on the website's remote database. So if you come across content that is not the git repository, it is probably stored in Wagtail on the Outreachy website server.

On the Outreachy webserver, we run Dokku. Dokku helps us deploy new code, manage our Let's Encrypt SSL certificates, and backup the Outreachy website database. Only Outreachy organizers have ssh access to push new code to the server. There should be no need for you to learn Dokku.

Concepts and Resources

If you are going to be modifying the website's Python code, you may need to learn about some new topics. It's best to keep these resources on hand and reference them as needed, rather than reading them all the way through before starting on a task.

When modifying the Django Python code, the following resources can be helpful:

• Django documentation overview
• Django tutorial
• Django topic guides
• Django models guide

Database concepts

Unfortunately, the Django documentation assumes you already have some basic knowledge of database concepts. We wish it was more friendly to people who are new to databases. This section is an attempt to document additional resources you may want to read on database concepts. If you are still having trouble understanding Django documentation, please ask for help.

The Django documentation will talk about the "relationship" between two Django class objects.

• What is a database relationship?

You will sometimes see fields of the type ForeignKey. Django has documentation on foreign key fields, but it assumes you know what a foreign key in a database is. If you are new to databases, we recommend reading about what a foreign key is:

• What is a primary key?
• What is a foreign key?
• How do primary keys and foreign keys relate to each other?

Setting up your development environment

You can run Django locally to test changes to the code, test creating new pages, test adding new users, etc. The local tests you run will not impact the main Outreachy website, only your local version of the website. You should test changes locally before submitting a pull request.

To set up your local development environment, first clone the repository to your local machine:

git clone https://github.com/outreachy/website.git

In order to develop with Python, you'll need the Python 3 development headers, so install them. For example, on Debian or Ubuntu Linux, you can use apt-get install python3-dev to install the Python 3 development headers. On other Linux distributions, it may be called python3-devel or installed by default with python packages.

You'll also need to install node.js. If you're running Linux, it's recommended you install it using your package manager. If you're using Windows or Mac, follow the installation instructions on the node.js website.

Lastly, you need to check whether you have libpq-dev (also called libpq-devel or postgresql-libs) installed using your package manager. That package is necessary to build psycopg2, a PostgreSQL database adapter for Python, from source. If you're using Arch Linux, make sure you also have base-devel installed.

Next, you'll need to create a new virtualenv. A "virtualenv" is a separate virtual environment for working on different Python projects. It's good practice to create a virtual environment for each Python project you're working on, in case they have conflicting dependencies, and so that you make sure to record all the dependencies for each project.

These instructions will help you create a new virtualenv that will have all the python packages installed that you need to work on the Outreachy website. We use pipenv for this purpose.

If you're using Linux, you may be able to install pipenv through your Linux package manager. On Debian or Ubuntu, you can run sudo aptitude install pipenv. Others distributions, like Arch Linux, may call it python-pipenv. Check Pipenv's documentation on installing pipenv for more information.

The following command will automatically create a virtual environment and install the Python dependencies specified in the Pipfile. If you need help understanding pipenv, run pipenv --help.

Make sure that you have not run pipenv shell yet, then run these two commands:

cd website
pipenv install

If you accidentally ran pipenv shell before those two commands, you should exit the shell using CTRL+d. Then run the two commands.

Now, you activate the virtual environment by typing the following command in the directory of the project:

pipenv shell

In addition to the Python packages that were installed for you when you created the virtualenv, you also need to install some Node.js packages; these will be placed in a node_modules directory inside your project folder. Make sure you have npm installed, then run:

npm install

If this is your first time creating a local version of the website for testing, you'll need to set up the local website database from scratch. The following command will create a new database with the models in the Outreachy website. The database will initially have no website pages, but will eventually store your local test pages.

./manage.py migrate

The next step is to create an admin account for the local website.

./manage.py createsuperuser

and run the tests.

PATH="$PWD/node_modules/.bin:$PATH" ./manage.py test

You'll need to set up a new internship round, following the instructions in the Django shell section and the internship round section.

Misc virtual env topics

Debugging pipenv

You can add the --verbose flag to any Pipenv command to understand what is happening behind the scenes. For example, when I was using a cellular network for my internet, pipenv install kept failing with the message "RuntimeError: Failed to lock Pipfile.lock!". When I enabled the verbose output, I could see that Pipenv was trying to clone a git repository, and that command was timing out after 1 minute with a pipenv.exceptions.ResolutionFailure error. It turned out my cellular network was very unstable, and would drop the connection for minutes at a time. The solution was to find a more stable internet connection (which had nothing to do with the file Pipfile.lock at all!).

Removing a virtual env

If you made a mistake in the directions above, you may need to remove your pipenv virtual environment. You can do that by running pipenv --rm in the website directory. If needed, you can delete the website directory and start over at the git clone command.

Updating package dependencies

Sometimes you may want to add a new Django extension that uses additional Python packages. That means you'll need to record the new Python packages used. Pipenv automatically records changes in the project's dependencies in the Pipfile when you add/remove packages.

You can add a package with the command pipenv install <package>

You can remove a package with the command pipenv uninstall <package>

Django shell

Django has a 'shell' mode where you can run snippets of Python code. You can exit the shell with CTRL+d at any time.

The Django shell takes a snapshot of the Python code base when you start the shell. If