Add a CONTRIBUTING.md file and simplify README

Now that the requirements files are split up in psf#37 and the local dev environment has been simplified, we can now add a detailed and welcoming contribution guide. This absorbs the install instructions from the README and expounds on the install and local development process so as to enable new developers to contribute to the project easly. There were no guidelines in the README as far as commit hygene or other contribution guidelines, but it wouldn't be difficult to add later. fixes: psf#19, psf#26, psf#27 relies on: psf#37
birdcar · May 16, 2021 · fb75ddd · fb75ddd
1 parent 7df7d2e
commit fb75ddd
Show file tree

Hide file tree

Showing 2 changed files with 170 additions and 65 deletions.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,168 @@
+# Contributing to Python in Eduucation
+
+:tada: Thanks for taking the time to contribute! :tada:
+
+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.
+
+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.
+
+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).
+
+With all of that in mind, here's how to get started with your contribution!
+
+## Table of Contents
+
+- [Contributing to Python in Eduucation](#contributing-to-python-in-eduucation)
+  - [Table of Contents](#table-of-contents)
+  - [Installation Guide](#installation-guide)
+    - [Prerequisites](#prerequisites)
+      - [Optional dependencies](#optional-dependencies)
+    - [Project setup](#project-setup)
+      - [1. Forking the repository](#1-forking-the-repository)
+      - [2. Using Git to clone your fork of the repository](#2-using-git-to-clone-your-fork-of-the-repository)
+      - [3. Create a Python virtual environment for the project](#3-create-a-python-virtual-environment-for-the-project)
+      - [4. Install the development dependencies for the project](#4-install-the-development-dependencies-for-the-project)
+      - [5. Run migrations & create a Django super user](#5-run-migrations--create-a-django-super-user)
+  - [Running the site locally](#running-the-site-locally)
+
+## Installation Guide
+
+### Prerequisites
+
+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. 
+
+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.
+
+- **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!
+- **On macOS:** `libjpeg` can be installed with [Homebrew](https://brew.sh/) by running `brew install jpeg` in your terminal
+- **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
+
+#### Optional dependencies
+
+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`.
+
+However, this is completely optional.
+
+### Project setup
+
+Now that our [prerequisites](#prerequisites) are installed. We can configure our development environment
+
+**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.
+
+
+#### 1. Forking the repository
+
+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.
+
+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:
+
+```shell
+gh repo fork psf/python-in-edu
+```
+
+#### 2. Using Git to clone your fork of the repository
+
+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.
+
+The first, using Git itself in your terminal, is done by running the following command:
+
+```shell
+# Replace $YOUR_GITHUB_USERNAME with your actual GitHub username
+git clone https://github.com/$YOUR_GITHUB_USERNAME/python-in-edu
+```
+
+The second, if you prefer to use the [GitHub CLI](https://cli.github.com/), is as follows:
+
+```shell
+# Replace $YOUR_GITHUB_USERNAME with your actual GitHub username
+gh repo clone $YOUR_GITHUB_USERNAME/python-in-edu
+```
+
+Finally, you'll want to move your terminal into that directory using the `cd` command:
+
+```shell
+cd python-in-edu
+```
+
+#### 3. Create a Python virtual environment for the project
+
+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.
+
+To do this, we'll use the `venv` module in the Python standard library:
+
+```shell
+python -m venv .venv
+```
+
+This will create a new directory in your local repository named `.venv`. 
+
+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.
+
+To do that, run the appropriate activate command for your operating system:
+
+```shell
+# on macOS and *nix run:
+source .venv/bin/activate
+
+# on Windows run:
+.venv\Scripts\activate.bat
+```
+
+#### 4. Install the development dependencies for the project
+
+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.
+
+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.
+
+If you've never done this before, you can install all the dependencies by running:
+
+```shell
+pip install -r requirements/dev.txt
+```
+
+From the root of the repository.
+
+#### 5. Run migrations & create a Django super user
+
+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.
+
+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:
+
+```shell
+# This command creates the database for us
+python manage.py migrate
+
+# This command walks us through creating a super user
+python manage.py createsuperuser
+```
+
+Congrats! You're now ready to start contributing to Python in Education. :tada:
+
+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/).
+
+## Running the site locally
+
+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:
+
+```shell
+python manage.py runserver
+```
+
+Alternatively, if you've installed the [heroku CLI](https://devcenter.heroku.com/articles/heroku-local), you can run the application using our production configuration:
+
+```shell
+# Must be run from the root of the repository, where Procfile is
+heroku local
+```
+
+To runt he test suite, run:
+
+```shell
+python manage.py test
+```
+
+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:
+
+```shell
+python -m smtpd -n -c DebuggingServer localhost:1025
+```
diff --git a/README.md b/README.md
@@ -6,72 +6,9 @@ We welcome contributions to this project! Our [issue tracker](https://github.com
 
 All contributors must agree to abide by our [Code of Conduct](https://github.com/psf/python-in-edu/blob/master/code_of_conduct.md).
 
-## Installation Guide
-
-In order to run this site locally, you'll want to clone this repository and install the requirements (check the [Mac Troubleshooting](#mac-troubleshooting) section if you face any errors):
-
-```
-git clone https://github.com/psf/python-in-edu.git
-cd python-in-edu
-python3 -m venv .venv
-source .venv/bin/activate
-pip install -r requirements.txt
-```
-
-You can then change directories into the python-in-edu folder and build the database:
-
-```
-python manage.py migrate
-```
-
-
-To run the project locally, run the following command in the terminal:
-
-```
-python manage.py runserver
-```
-
-If you use [heroku cli installed on your system](https://devcenter.heroku.com/articles/heroku-local), simply run:
-
-```
-heroku local
-```
-
-To test, run:
-
-```
-python manage.py test
-```
-
-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):
-
-    python -m smtpd -n -c DebuggingServer localhost:1025
+## Contributing
 
+If you'd like to contribute to this project, see our [Contribution guide](/CONTRIBUTING.md) for detailed instructions on how to help.
 ## Notes
 
 We use the [Spirit project](https://spirit-project.com/) for our forums.
-
----
-
-<h2 id="mac-troubleshooting">Mac Troubleshooting</h2>
-
-### Postgres
-
-If you don't have an installation of Postgres on your system, you might run into the following error:
-
-```
-Error: pg_config executable not found.
-```
-
-[Install Postgres](https://postgresapp.com/) to resolve this issue.
-
-### Pillow
-
-If your Pillow installation fails during installing the requirements with the following message:
-
-```
-The headers or library files could not be found for jpeg,
-a required dependency when compiling Pillow from source.
-```
-
-You can resolve this by installing [jpeg](https://formulae.brew.sh/formula/jpeg) using [homebrew](https://brew.sh/).