Contributing to the SciPost codebase

Our self-served Git depot at scipost-codebases.org hosts the main SciPost repository (access credentials required).

Pull requests are admitted from members of our Development Team. Please conform to all conventions below in any pull request you create.

Coding conventions

Our starting points are the PEP 8 specification, and the Django style.

We further default to the conventions in Black.

Hereby follow some extra specializations.

To ease your work, if you have an editor with EditorConfig support, you can use our .editorconfig file at the base of the repository.

Line length

We deviate from PEP 8 and set the maximal line length to 88.

Docstrings

Docstrings are in reStructruredText (of course), and should fit within the allowed line length of 88.

Templates

Indentation

There are no fixed, generally-accepted conventions for indentation in Django templates.

The Django documentation’s Python style paragraph specifies 4 spaces for Python, and 2 spaces for HTML (note however the amusing fact that the Django docs themselves, when displaying template code, do not follow this convention and use 4 spaces).

The question remains what to do with template tags. We adopt the convention that

• template tags should be indented two spaces, just like HTML elements

For example: please write:

<div>
  <ul>
    {% for publication in publications %}
      <li>{{ publication }}</li>
    {% endfor %}
  </ul>
</div>

(2 spaces between HTML tags and/or template tags), instead of:

<div>
    <ul>
    {% for publication in publications %}
    <li>{{ publication }}</li>
    {% endfor %}
    </ul>
</div>

in which the following crimes are committed: 4 spaces between HTML tags, no spaces between HTML and template tags (and their reverse crimes).

Though this means that the rendered HTML will have some extra spaces, who cares? The source is displayed more nicely, and HTML is space-insensitive (though an evil hacker would be able to see from the spacings that you did use some tags; but which one(s)?).

Curly braces

Though this is already specified in the Django coding style, we repeat it here to avoid you the risk of life-threatening injuries. Put one space between braces and tag contents, so:

{{ publication }}

instead of the harder-to-read:

{{publication}}