djangoproject.com source code

To run locally, you can either:

• Install and run from a virtual environment
• Run with docker compose (see below)

Install and run locally from a virtual environment

1. Create aPython 3.8+ virtualenv and activate it

2. Install dependencies:

   python3 -m pip install -r requirements/dev.txtnpm install

   Alternatively, use the make task:

   make install

3. Make a directory to store the project's data (MEDIA_ROOT,DOC_BUILDS_ROOT,etc.). We'll use~/.djangoproject for example purposes. Create a sub-directorynamedconf inside that directory:

   mkdir -p ~/.djangoproject/conf

   Create asecrets.json file in theconf directory, containing somethinglike:

   {  "secret_key": "xyz",  "superfeedr_creds": ["any@email.com", "some_string"],  "db_host": "localhost",  "db_password": "secret",  "trac_db_host": "localhost",  "trac_db_password": "secret"}

4. Addexport DJANGOPROJECT_DATA_DIR=~/.djangoproject (without the backticks)to your~/.bashrc (or~/.zshrc if you're using zsh,~/.bash_profile ifyou're on macOS and using bash) file and then runsource ~/.bashrc (orsource ~/.zshrc, orsource ~/.bash_profile) to load the changes.

5. Create databases:

   createuser -d djangoproject --superusercreatedb -O djangoproject djangoprojectcreateuser -d code.djangoproject --superusercreatedb -O code.djangoproject code.djangoproject

6. Setting up database access

   If you are using the default postgres configuration, chances are you willhave to give a password for the newly created users to be able touse them for Django:

   psqlALTER USER djangoproject WITH PASSWORD 'secret';ALTER USER "code.djangoproject" WITH PASSWORD 'secret';\d

   (Use the same passwords as the ones you've used in yoursecrets.json file)

7. Create tables:

   psql -d code.djangoproject < tracdb/trac.sqlpython -m manage migrate

8. Create a superuser:

   python -m manage createsuperuser

9. Populate the www and docs hostnames in the django.contrib.sites app:

   python -m manage loaddata dev_sites

10. For docs (next step requiresgettext):

    python -m manage loaddata doc_releasespython -m manage update_docs_and_index

11. For dashboard:

    To load the latest dashboard categories and metrics:

    python -m manage loaddata dashboard_production_metrics

    Alternatively, to load a full set of sample data (takes a few minutes):

    python -m manage loaddata dashboard_example_data

    Finally, make sure the loaded metrics have at least one data point (thismakes API calls to the URLs from the metrics objects loaded above and maytake some time depending on the metrics chosen):

    python -m manage update_metrics

12. Compile the CSS (only the source SCSS files are stored in the repository):

    make compile-scss

13. Finally, run the server:

    make run

    This runs both the main site ("www") as well as thedocs and dashboard site in the same process.Openhttp://www.djangoproject.localhost:8000/,http://docs.djangoproject.localhost:8000/,orhttp://dashboard.djangoproject.localhost:8000/.

Running the tests

We use GitHub actions for continuous testing andGitHub pull request integration. If you're familiarwith those systems you should not have any problems writing tests.

Our test results can be found here:

• https://github.com/django/djangoproject.com/actions

For local development don't hesitate to installtox to run the website's test suite.

Then in the root directory (next to themanage.py file) run:

tox

Behind the scenes, this will run the usualpython -m manage test managementcommand with a preset list of apps that we want to test as well asflake8 for code quality checks. Wecollect test coverage data as part of that tox run, to show the resultsimply run:

python -m coverage report

or for a HTML-based report:

python -m coverage html

(Optional) In case you're using an own virtualenv you can also run thetests manually using thetest task of theMakefile. Don't forget toinstall the test requirements with the following command first though:

python -m pip install -r requirements/tests.txt

Then run:

make test

or simply the usual test management command:

python -m manage test [list of app labels]

Supported browsers

The goal of the site is to target various levels of browsers, depending ontheir ability to use the technologies in use on the site, such as HTML5, CSS3,SVG, webfonts.

We're followingMozilla's examplewhen it comes to categorizing browser support.

• Desktop browsers, except as noted below, areA grade, meaning thateverything needs to work.
• IE < 11 isnot supported (based on Microsoft's support).
• Mobile browsers should be consideredB grade as well.Mobile Safari, Firefox on Android and the Android Browser should supportthe responsive styles as much as possible but some degradation can't beprevented due to the limited screen size and other platform restrictions.

File locations

Static files such as CSS, JavaScript or image files can be found in thedjangoproject/static subdirectory.

Templates can be found in thedjangoproject/templates subdirectory.

Styles

CSS is written inScss and compiled viaLibsass.

Run the following to compile the Scss files to CSS:

make compile-scss-debug

Alternatively, you can also run the following command in a separate shellto continuously watch for changes to the Scss files and automatically compileto CSS:

make watch-scss

Running all at once

Optionally you can use a tool likeForemanto run all process at once:

• the site (similar towww.djangoproject.com) onhttp://0.0.0.0:8000/ to be usedwith the modified /etc/hosts file (see above)
• themake task to automatically compile the SCSS files to CSS files

This is great during development. Assuming you're using Foreman simply run:

foreman start

If you just want to run one of the processes defined above use therun subcommand like so:

foreman run web

That'll just run the www server.

Check out theProcfile file for all the process names.

JavaScript libraries

This project usesBower to manage JavaScript libraries.

At any time, you can run it to install a new library (e.g.,jquery-ui):

npm run bower install jquery-ui --save

or check if there are newer versions of the libraries that we use:

npm run bower ls

If you need to update an existing library, the easiest way is to change theversion requirement inbower.json and then to runnpm run bower install again.

We commit the libraries to the repository, so if you add, update, or remove alibrary frombower.json, you will need to commit the changes indjangoproject/static too.

Documentation search

When runningpython -m manage update_docs_and_index to build all documents it will alsoautomatically index every document it builds in the search engine as well.In case you've already built the documents and would like to reindex thesearch index, run the command:

python -m manage update_index

This is also the right command to run when you work on the search featureitself. You can pass the-d option to try to drop the search indexfirst before indexing all the documents.

Updating metrics from production

The business logic for dashboard metrics is edited via the admin interface andcontained in the models in thedashboard app (other thanDataum, whichcontains the data itself). From time to time, those metrics should be extractedfrom a copy of the production database and saved to thedashboard/fixtures/dashboard_production_metrics.json file.

To update this file, run:

python -m manage dumpdata dashboard --exclude dashboard.Datum --indent=4 > dashboard_production_metrics.json

Translation

We're using Transifex to help manage the translation process. TheTransifex client app is required. To install it, run:

curl -o- https://raw.githubusercontent.com/transifex/cli/master/install.sh | bash

Before using the command-line Transifex client, create~/.transifexrcaccording to the instructions athttps://docs.transifex.com/client/client-configuration. You'll need to be amember of the Django team in theDjango organization at Transifex. Forinformation on how to join, please see theTranslationssection of the documentation on contributing to and localizing Django.

Since this repo hosts three separate sites, our.po files are organized bywebsite domain. At the moment, we have:

• dashboard/locale/ contains the translation files forhttps://dashboard.djangoproject.com
• docs/locale/ contains the translation files forhttps://docs.djangoproject.com (only for the strings in this repository;translation of the documentation itself is handled elsewhere)
• locale/ contains the translation files forhttps://www.djangoproject.com(including strings from all apps other thandashboard anddocs)

Important: To keep this working properly, note that any templates for thedashboard anddocs appsmust be placed in the<app name>/templates/<app name>/ directory of the respective app,not inthedjangoproject/templates/ directory.

Updating messages on Transifex

When there are changes to the messages in the code or templates, a member ofthe translations team will need to update Transifex as follows:

1. Regenerate the English (only) .po file:

   python -m manage makemessages -l en

   (Never update alternate language .po files using makemessages. We'll updatethe English file, upload it to Transifex, then later pull the .po files withtranslations down from Transifex.)

2. Push the updated source file to Transifex:

   tx push -s

3. Commit and push the changes to GitHub:

   git commit -m "Updated messages" locale/en/LC_MESSAGES/*git push

Updating translations from Transifex

Anytime translations on Transifex have been updated, someone should updateour translation files as follows:

1. Review the translations in Transifex and add to the space-delimitedLANGUAGES list inupdate-translations.sh, any new languages that havereached 100% translation.

2. Pull the updated translation files:

   ./update-translations.sh

3. Usegit diff to see if any translations have actually changed. If not,you can just revert the .po file changes and stop here.

4. Compile the messages:

   python -m manage compilemessages

5. Run the test suite one more time:

   python -m manage test

6. Commit and push the changes to GitHub:

   git commit -m "Updated translations" locale/*/LC_MESSAGES/*git push

Running Locally with Docker

1. Build the images:

   docker-compose build

2. Spin up the containers:

   docker-compose up

3. View the site athttp://localhost:8000/

4. Run the tests:

   docker-compose exec web toxdocker-compose exec web python -m manage test

Pre-commit checks

pre-commit is a framework for managing pre-commithooks. These hooks help to identify simple issues before committing code forreview. By checking for these issues before code review it allows the reviewerto focus on the change itself, and it can also help to reduce the number of CIruns.

To use the tool, first installpre-commit and then the git hooks

$python3 -m pip install pre-commit$python3 -m pre_commit install

On the first commitpre-commit will install the hooks, these areinstalled in their own environments and will take a short while toinstall on the first run. Subsequent checks will be significantly faster.If the an error is found an appropriate error message will be displayed.If the error was withisort then the tool will go ahead and fix them foryou. Review the changes and re-stage for commit if you are happy withthem.