Skip to content

Developer Wiki

Jump to bottom
Oskar Triebe edited this page Feb 20, 2024 · 20 revisions

This wiki is for development purposes of the NeuralProphet library.
The user documentation can be found here.

Contributing Process

In summary, follow the steps below to make your first contribution. If you want to have more details on every step, check out this beginner's guide to contributing to a GitHub project.

  1. Setup your development environment for NeuralProphet following this tutorial
  2. Find an issue to work on by filtering on the label https://github.com/ourownstory/neural_prophet/labels/good%20first%20issue. Comment under the issue, you wish to take over to prevent multiple people working on the same issue.
  3. Pull the latest changes from remote: git pull upstream main
  4. Push changes to your fork: git push origin main
  5. Create a new branch from main to work on: git checkout -b BRANCH_NAME
  6. Make some changes in your local repository
  7. Stage the changes: git add -A
  8. Commit the changes: git commit -m "DESCRIPTION OF CHANGES"
  9. Push changes to your fork: git push origin BRANCH_NAME
  10. Do a pull request: If you visit https://github.com/ourownstory/neural_prophet now, there should be a green button saying "Compare & pull request", click on it and describe the changes you did. Now you only need to wait for a review and respond to any feedback.

Congratulations, you just contributed your first pull request. For your next issue just follow the steps starting from number 2.

Writing documentation

NeuralProphet uses the Sphinx documentation framework to build the documentation website, which is hosted via Github Pages on www.neuralprophet.com.

The documentation's source is enclosed in the docs folder. Whereas the main branch only contains the basic source files, the branch gh-pages entails the build data (with folders docs/html and docs/doctrees) and is used for deployment.

Docstring

Docstrings need to be formatted according to NumPy Style in order to display their API reference correctly using Spinx. Please refer to Pandas Docstring Guide for best practices.

The length of line inside docstrings block must be limited to 80 characters to fit into Jupyter documentation popups.

You can check for adherence to the style guide by running:

pydocstyle --convention=numpy path/my_file.py

(You may need to install the tool first. On Linux: sudo apt install pydocstyle.)

Example

See how Pandas does this for melt in their melt documentation page and how it looks in the melt docstring.

Docstring architecture sample:

def return_first_elements(n=5):
    """
    Return the first elements of a given Series.

    This function is mainly useful to preview the values of the
    Series without displaying all of it.

    Parameters
    ----------
    n : int
        Number of values to return.

    Return
    ------
    pandas.Series
        Subset of the original series with the n first values.

    See Also
    --------
    tail : Return the last n elements of the Series.
    Examples
    --------
    If you have multi-index columns:
    >>> df.columns = [list('ABC'), list('DEF')]
    >>> df
       A  B  C
       D  E  F
    0  a  1  2
    1  b  3  4
    2  c  5  6
    """
    return self.iloc[:n]

Notebooks: Adding new tutorials (or renaming existing)

All Jupyter notebooks should be located inside docs/source/ subfolders tutorials and how-to-guides. When you add a new tutorial notebook, please add the new tutorial file names to the index.rst file inside docs/source/how-to-guides/ or docs/source/tutorials/, respectively. Follow Sphinx restructured text syntax.

They are then auto-rendered using the Sphinx extension nbsphinx to html files in the documentation website.

Building documentation

To build the documentation and publish the new website

  1. Remove branch protection from website branch (allow force push and do not require any reviews)

  2. Update website branch to main

    • git fetch make sure you’ve got the latest main branch version locally
    • git checkout website go into website branch
    • Variant 1 (try first)
      • git merge origin/main
      • git push origin website
    • Variant 2
      • git reset --hard origin/main reset website branch to main branch (meaning all changes of main go into website, changes in website would get lost, but there should be none)
      • git push origin website -f -f means force, meaning override the website branch also on github (origin)

  3. GitHub action automatically publishes the new website

For local testing

  • GitHub action config for website
  • Website is built with sphinx and pandox, locally with sphinx-build docs/source _site -j4 -E (or shortly with make html in the docs folder and then open html/index.html). For that you need to install:
    • poetry install --with=docs
    • brew install pandoc
  • Hosting is done with Github pages
  • Changes should be reflected instantly on the documentation website.

Testing and Code Coverage

We are using PyTest to run tests within our projects. All tests can be found in tests/ directory.

All tests can be triggered via the command:

pytest tests -v

Running specific tests can be done by running the command:

pytest tests -k "name_of_test"

We are using pytest-cov and codecov to create transparent code coverage reports. To locally trigger and output a code coverage report via the commandline, run the following command:

pytest tests -v --cov=./

Continous Integration

We are using Github Actions to setup a CI pipeline. The creation as well as single commits to a pull request trigger the CI pipeline.

Currently there is one workflow called .github/worklfows/ci.yml to trigger testing, create code coverage reports via pytest-cov and subsequently uploading reports via codecov for the major OS systems (Linux, Mac, Windows).

Style

We deploy Black, the uncompromising code formatter, so there is no need to worry about style. Beyond that, where reasonable, for example for docstrings, we follow the Google Python Style Guide

As for Git practices, please follow the steps described at Swiss Cheese for how to git-rebase-squash when working on a forked repo. (Update: all PR are now squashed, so you can skip this step, but it's still good to know.)

String formatting

Please use the more readable f-string formatting style.

Typing

We try to use type annotations across the project to improve code readability and maintainability.

Please follow the official python recommendations for type hints and PEP-484.

Postponing the evaluation type annotations and python version

The Postponed Evaluation of Annotations PEP 563 provides major benefits for type annotations. To use them with our currently support python versions we must use the following syntax:

from __future__ import annotations

Circular imports with type annotations

When using type annotations, you may encounter circular imports. To avoid this, you can use the following pattern based on the typing.TYPE_CHECKING constant:

from __future__ import annotations
from typing import TYPE_CHECKING

# Imports only needed for type checking
if TYPE_CHECKING:
    from my_module import MyType

Tips for Windows User:

To contribute to NeuralProphet from Windows install WSL to run Linux terminal in Windows.

1.Install WSL2.

2.Install libraries

a. pip:This will allow users to quick install using pip.

sudo apt install pip

b.For any ”name” not found try.

pip install <name>

Notes:

  • To install NeuralProphet in dev mode, create a venv using the Linux terminal on the subsystem drive (not the mount).
  • For any statement error try using sudo and --user which will then allow administrator access to perform the action.

Releasing

Release on Pypi

  1. Create release branch from main (latest version) with git checkout -b release/x.y.z
  2. Update version number in project (currently in pyproject.toml), set it to x.y.z
  3. Stage and commit changes, git commit -m “bump version number to x.y.z"
  4. Upload changes git push
  5. Set token (only first time)
    1. (For test.pypi: poetry config pypi-token.test-pypi <your-test-pypi-token> → doesn't work yet)
    2. For pypi: poetry config pypi-token.pypi <you-pypi-token> (get your token from https://pypi.org/manage/account/token/)
  6. Build and publish with poetry poetry publish --build
  7. On Github create pull request from release/x.y.z to main (to update version number in main too)
  8. Create a git tag after the pull request is merged
    1. Update local directory git checkout main and git pull
    2. Create a git tag with git tag x.y.z
    3. Upload the git tag with git push --tags
  9. Create a release on Github
    1. Click on Choose a tag and select x.y.z
    2. Name it with Release x.y.z or Beta x.y.z
    3. Auto generate release notes (button on the right side)
    4. Clean up the release notes and group them
    5. Set as pre-release or latest release depending on the type
    6. Publish the release
  10. Make an announcement of the release in Slack

Test the release

Install neuralprophet in an empty environment and check if everything works

Create environment with poetry

  1. poetry init
  2. poetry shell
  3. poetry add neuralprophet==x.y.z

Create environment with venv

  1. python3.9 -m venv .venv
  2. source .venv/bin/activate
  3. pip install neuralprophet==x.y.z

Housekeeping

Close the milestone

Clone this wiki locally