How to Contribute to Space Telescope Notebooks

Contributions are welcome from both inside and outside the Institute. Whether contibuting, commenting, or giving feedback, we expect everyone to follow our code of conduct.

Submission Policies

These are the high-level notebook submission policies. More comprehensive guidelines may be given in the other repositories, but following these guidelines is a necessary first step.

Foundations

Notebook code cells must be written in Python. Notebooks must use the kernel name python3. Version support is detailed in the Version Support Guide. Notebook documentation cells are written in Markdown.

Do NOT commit executed Notebooks. This needlessly inflates the size of our repositories and is a bit of a nightmare to handle.

Files and directories

All notebooks must be in a sub-directory of the main notebooks directory. The directory name and the names of the files contained within it cannot contain whitespace or non-printable characters. (Underscores should be used in lieu of a space)

In general, unique notebooks on different topics should each be in their own directory with only one notebook. However, multi-part notebooks are best implemented as multiple notebooks in the same directory. They will then be run in alphabetical order, sharing the same execution directory. Hence, a "Part 1" can generate files that are used in later parts.

Given a minimal Python environment, the notebook(s) should run correctly after the requirements are installed.
Each notebook directory must contain one or more .ipynb extension files, or directories that themselves contain notebooks. Each directory must contain a file named requirements.txt which lists the dependencies for the notebooks in that directory and any sub-directories. The "requirements.txt" file in a notebook directory follows these rules/guidelines:

The requirements.txt file must be non-empty.
All package requirements in the requirements.txt file must use the '>=' operator, never '=='. Security updates may require newer version of package dependencies to be installed in future builds.
When versions are given as ">=", that should be interpreted as "last known working version". The prime goal here is to ensure there is a record of what version of dependencies is known to produce the output the notebook author intended, ensuring the scientific results are reproducible.

Authorship

A notebook must explicitly list:

An author(s): the individual(s) who wrote the notebook
An owner: the branch, team, or group that maintains the notebook content in the future. For external contributors (outside of STScI), the notebook author will be assigned as the owner. The owner is expected to periodically check the notebook for science relevance.

PEP8 Compliance

In addition to the Notebook Style Guide, any code in the notebook should be PEP8 compliant. PEP 8 compliance can be checked with the flake8 and pycodestyle_magic packages. These packages can be installed using pip:

$ pip install flake8 pycodestyle_magic

Then add these two lines in a cell at the beginning of the notebook:

%load_ext pycodestyle_magic

%flake8_on --ignore E261,E501,W291,W293

Step-by-step Guide

Ready to contribute? See the git workflow document; the preferred method is the "Forking Workflow" listed under "Workflow Instructions".