Add code formatting and staging information, among other tidying
# Developer docs
-The intended audience for this document is future developers of TWLight. Hi!
+The intended audience for this document is developers of TWLight. Hi!
To get set up with TWLight locally you will need [Docker](https://www.docker.com/) and [Docker Compose](https://docs.docker.com/compose/).
+TWLight runs on Django 1.11 (a Django 2 upgrade will be taking place before 1.11 end of life), and uses Python 3.7.
+
## Shell scripts
A suite of shell scripts for performing various functions can be found in the /bin folder.
@@ -33,18 +35,26 @@ When working on TWLight locally you may want example data reflecting the live to
This script can only be generated with an empty database, after you have logged in to an account you want to be made a superuser (the script looks for a single account in the database and makes it a Django superuser).
+## Code formatting
+
+We enforce code formatting via [black](https://github.com/psf/black) - tests will fail (both locally and on Travis) if black detects an issue with your code formatting. Run black on your code before pushing it via `docker-compose exec twlight /venv/bin/black -t py37 /app/TWLight`.
+
## Translation
[Translations](https://github.com/wikipedialibrary/TWLight/blob/master/docs/sysadmin.md#translations) are supported in the platform. Please make sure to correctly comment new or updated strings with guidance for translators - to do so, write a comment to the line preceding the string which starts `# Translators:` in python files or `{% comment %}Translators:` in HTML.
In HTML files, make sure to wrap multiline strings with `{% blocktrans trimmed %}`, not just `{% blocktrans %}`, to avoid whitespace and indentation formatting issues.
-Where possible, try to keep code and HTML tags outside of strings (i.e. `<p>{% trans "Text" %}</p>` rather than `{% trans "<p>Text</p>" %}` to avoid confusion for translators.
+Where possible, try to keep code and HTML tags outside of strings (i.e. `<p>{% trans "Text" %}</p>` rather than `{% trans "<p>Text</p>" %}` to avoid confusion for translators. Don't, however, break up sentences into multiple translation blocks. Translators need to see the entire context of a string to translate it accurately.
## Pushing changes
When filing Pull Requests for code changes, you should _not_ include translation updates and are not _required_ to include migration files. When changes are merged into the Master branch, Travis CI runs checks on the build and if it passes, pushes the changes through to the Production branch, which is then pulled to the live tool. This will run migration and string localization processes automatically.
+## Staging environment
+
+We have a staging environment hosted adjacent to the production site at https://twlight-staging.wmflabs.org/. If you would like to test your changes in this environment, to test against live data or in a close-to-production environment, please let a member of the TWL team know and we can pull your code down.
+
## Specific code changes
Some bits and pieces of advice and guidance on changing specific areas of the codebase.
@@ -72,7 +82,7 @@ All four places referenced there must be updated:
## PyCharm setup
-This project can be set up via PyCharm using its support for Docker. Wikimedia developers can get free access to PyCharm Professional (required for Docker support) - please contact The Wikipedia Library for instructions.
+This project can be set up via PyCharm using its support for Docker. Wikimedia developers can get free access to PyCharm Professional (required for Docker support) - please contact The Wikipedia Library team for instructions.
### Process
