|
| 1 | +# Contributing to Python in Eduucation |
| 2 | + |
| 3 | +:tada: Thanks for taking the time to contribute! :tada: |
| 4 | + |
| 5 | +First, we encourage you to introduce yourself to the community [in our forums](http://education.python.org/forum/category/3/introductions/) before leaping into action. |
| 6 | + |
| 7 | +Once you've done that, our [issue tracker](https://github.com/psf/python-in-edu/issues) has open bugs, feature requests, etc. for you to chose from. |
| 8 | + |
| 9 | +Finally, and most importantly, all contributors must agree to abide by our [Code of Conduct](https://github.com/psf/python-in-edu/blob/master/code_of_conduct.md). |
| 10 | + |
| 11 | +With all of that in mind, here's how to get started with your contribution! |
| 12 | + |
| 13 | +## Table of Contents |
| 14 | + |
| 15 | +- [Contributing to Python in Eduucation](#contributing-to-python-in-eduucation) |
| 16 | + - [Table of Contents](#table-of-contents) |
| 17 | + - [Installation Guide](#installation-guide) |
| 18 | + - [Prerequisites](#prerequisites) |
| 19 | + - [Optional dependencies](#optional-dependencies) |
| 20 | + - [Project setup](#project-setup) |
| 21 | + - [1. Forking the repository](#1-forking-the-repository) |
| 22 | + - [2. Using Git to clone your fork of the repository](#2-using-git-to-clone-your-fork-of-the-repository) |
| 23 | + - [3. Create a Python virtual environment for the project](#3-create-a-python-virtual-environment-for-the-project) |
| 24 | + - [4. Install the development dependencies for the project](#4-install-the-development-dependencies-for-the-project) |
| 25 | + - [5. Run migrations & create a Django super user](#5-run-migrations--create-a-django-super-user) |
| 26 | + - [Running the site locally](#running-the-site-locally) |
| 27 | + |
| 28 | +## Installation Guide |
| 29 | + |
| 30 | +### Prerequisites |
| 31 | + |
| 32 | +There are some operating-system specific libraries and dependencies you'll need to have installed before you can install the dependencies for our Django app. |
| 33 | + |
| 34 | +Specifically, because our application relies on [Pillow](https://pillow.readthedocs.io/en/latest/index.html) you'll need to ensure that `libjpeg` is installed in your system prior to installing our Python specific dependencies. |
| 35 | + |
| 36 | +- **On Windows:** You shouldn't need to do anything. Please [open an issue](https://github.com/psf/python-in-edu/issues/new) and let us know if that's not the case! |
| 37 | +- **On macOS:** `libjpeg` can be installed with [Homebrew](https://brew.sh/) by running `brew install jpeg` in your terminal |
| 38 | +- **On Linux:** `libjpeg` will be provided by your specific distro's package manager. For example, in Ubuntu/Debian you would install `libjepeg` by running `sudo apt install libjpeg-dev` in your terminal |
| 39 | + |
| 40 | +#### Optional dependencies |
| 41 | + |
| 42 | +This Django app is deployed to Heroku, so if you'd like to have your development environment mirror production as closely as possible, you'll want to install the [Heroku CLI](https://devcenter.heroku.com/articles/heroku-cli) so you can use `heroku local` to serve the application locally, rather than `python manage.py runserver`. |
| 43 | + |
| 44 | +However, this is completely optional. |
| 45 | + |
| 46 | +### Project setup |
| 47 | + |
| 48 | +Now that our [prerequisites](#prerequisites) are installed. We can configure our development environment |
| 49 | + |
| 50 | +**NOTE:** The following instructions assume very little familiarity with Git, GitHub, and contributing to Python/Django open source projects. If you're already a pro at contributing to open source, feel free to skim our setup instructions and then get to work. |
| 51 | + |
| 52 | + |
| 53 | +#### 1. Forking the repository |
| 54 | + |
| 55 | +First, [fork the repository](https://docs.github.com/en/github/getting-started-with-github/fork-a-repo) so that you have your own copy of the application to work from. |
| 56 | + |
| 57 | +The easiest way to do this is to [click the "Fork" button in the top right hand side of this page](https://github.com/psf/python-in-edu/fork). Alternatively, if you prefer to use the [GitHub CLI](https://cli.github.com/), you can fork the repository by running: |
| 58 | + |
| 59 | +```shell |
| 60 | +gh repo fork psf/python-in-edu |
| 61 | +``` |
| 62 | + |
| 63 | +#### 2. Using Git to clone your fork of the repository |
| 64 | + |
| 65 | +Now that your repository has been forked, you'll want to clone that forked version of the repository to your computer using Git. There are two ways to do this. |
| 66 | + |
| 67 | +The first, using Git itself in your terminal, is done by running the following command: |
| 68 | + |
| 69 | +```shell |
| 70 | +# Replace $YOUR_GITHUB_USERNAME with your actual GitHub username |
| 71 | +git clone https://github.com/$YOUR_GITHUB_USERNAME/python-in-edu |
| 72 | +``` |
| 73 | + |
| 74 | +The second, if you prefer to use the [GitHub CLI](https://cli.github.com/), is as follows: |
| 75 | + |
| 76 | +```shell |
| 77 | +# Replace $YOUR_GITHUB_USERNAME with your actual GitHub username |
| 78 | +gh repo clone $YOUR_GITHUB_USERNAME/python-in-edu |
| 79 | +``` |
| 80 | + |
| 81 | +Finally, you'll want to move your terminal into that directory using the `cd` command: |
| 82 | + |
| 83 | +```shell |
| 84 | +cd python-in-edu |
| 85 | +``` |
| 86 | + |
| 87 | +#### 3. Create a Python virtual environment for the project |
| 88 | + |
| 89 | +It's always a good idea to create a new [virtual environment](https://docs.python.org/3/tutorial/venv.html) for every Python project you work on. |
| 90 | + |
| 91 | +To do this, we'll use the `venv` module in the Python standard library: |
| 92 | + |
| 93 | +```shell |
| 94 | +python -m venv .venv |
| 95 | +``` |
| 96 | + |
| 97 | +This will create a new directory in your local repository named `.venv`. |
| 98 | + |
| 99 | +We then want to "activate" that virtual environment to ensure that any packages we install are only installed for that project and not for the rest of our computer. |
| 100 | + |
| 101 | +To do that, run the appropriate activate command for your operating system: |
| 102 | + |
| 103 | +```shell |
| 104 | +# on macOS and *nix run: |
| 105 | +source .venv/bin/activate |
| 106 | + |
| 107 | +# on Windows run: |
| 108 | +.venv\Scripts\activate.bat |
| 109 | +``` |
| 110 | + |
| 111 | +#### 4. Install the development dependencies for the project |
| 112 | + |
| 113 | +We've forked the repository, cloned it, and we're now in a virtual environment. It's now safe to install the project's dependencies using pip. |
| 114 | + |
| 115 | +The dependencies in this project are broken into requirements files for specific environments. For local development, you only need to install the dependencies declared in the `requirements/dev.txt` requirements file. |
| 116 | + |
| 117 | +If you've never done this before, you can install all the dependencies by running: |
| 118 | + |
| 119 | +```shell |
| 120 | +pip install -r requirements/dev.txt |
| 121 | +``` |
| 122 | + |
| 123 | +From the root of the repository. |
| 124 | + |
| 125 | +#### 5. Run migrations & create a Django super user |
| 126 | + |
| 127 | +Finally, in order to administer the site locally, you'll need to create a local database to work with and a Django super user so that you can log in to the Django Admin. |
| 128 | + |
| 129 | +Make sure that you're in the `python-in-edu` directory that contains the `mangage.py` file in your terminal, and then run the following commands: |
| 130 | + |
| 131 | +```shell |
| 132 | +# This command creates the database for us |
| 133 | +python manage.py migrate |
| 134 | + |
| 135 | +# This command walks us through creating a super user |
| 136 | +python manage.py createsuperuser |
| 137 | +``` |
| 138 | + |
| 139 | +Congrats! You're now ready to start contributing to Python in Education. :tada: |
| 140 | + |
| 141 | +Be sure to [create a new branch](https://git-scm.com/book/en/v2/Git-Branching-Basic-Branching-and-Merging) for your work, and [open a Pull Request](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request) on GitHub whenever you're ready for someone to review your code. If you're new to Git, we'd also highly recommend reading through this guide on [how to write good commit messages](https://chris.beams.io/posts/git-commit/). |
| 142 | + |
| 143 | +## Running the site locally |
| 144 | + |
| 145 | +Assuming that you've [installed and confugred the project as described above](#project-setup) you can run the Django application locally using Django's built-in development server: |
| 146 | + |
| 147 | +```shell |
| 148 | +python manage.py runserver |
| 149 | +``` |
| 150 | + |
| 151 | +Alternatively, if you've installed the [heroku CLI](https://devcenter.heroku.com/articles/heroku-local), you can run the application using our production configuration: |
| 152 | + |
| 153 | +```shell |
| 154 | +# Must be run from the root of the repository, where Procfile is |
| 155 | +heroku local |
| 156 | +``` |
| 157 | + |
| 158 | +To runt he test suite, run: |
| 159 | + |
| 160 | +```shell |
| 161 | +python manage.py test |
| 162 | +``` |
| 163 | + |
| 164 | +And finally, if you want to use or test email functionality locally, you'll need to [run a simple SMTP server](https://docs.djangoproject.com/en/3.1/topics/email/#configuring-email-for-development) in a separate terminal window/tab: |
| 165 | + |
| 166 | +```shell |
| 167 | +python -m smtpd -n -c DebuggingServer localhost:1025 |
| 168 | +``` |
0 commit comments