../_images/scikit-rf-title-flat.svg

Contributing to scikit-rf

Sponsoring the Project

It is possible to sponsor the maintainers and developers of the scikit-rf package, using the GitHub Sponsor option (“Sponsor this project”) visible on the scikit-rf GitHub page.

Sponsoring is one more way to contribute to open source: financially supporting the people who build and maintain it. Funding individuals helps them keep doing important work, expands opportunities to participate, and gives developers the recognition they deserve.

Contributing to the Code

Note

if you feel that the instructions on this page are too complicated, but you still would like to contribute, do not hesitate to email us on the scikit-rf mailing list or join us in the scikit-rf Slack channel or the scikit-rf Matrix/Element channel to get some help.

skrf uses the “Fork + Pull” collaborative development model. If this is new to you, see GitHub’s articles on forking and pull requests.

Basically, you will:

  1. Fork the GitHub scikit-rf repository,

  2. Make your modifications.

  3. Then send a pull request (PR) for your additions to be merged into the main scikit-rf repository. Your proposal will be reviewed or discussed and you may receive some comments which only aim to make your contribution as great as possible!

Tip

When making your modification locally, you may need to work into a dedicated development environment in order to not interfere with the scikit-rf package that you have already installed. You can use for example anaconda environment. In order for the anaconda environment to find your local scikit-rf repo, use the convenient conda-develop command.

Pre-commit

You can use pre-commit to automate your code quality checks and perform automated fixes in scikit-rf.

To enable pre-commit on your computer (make sure it is installed first), open a terminal and Navigate to the scikit-rf/ directory that contains your clone of scikit-rf’s repository, then run:

pre-commit install

Note

Once pre-commit has been installed for a repository, pre-commit will run every time you try to commit a change. If any pre-commit checks fail, or if pre-commit changes any files, it will be necessary to redo git add on the changed files and git commit once again.

Tip

To commit a change without running pre-commit, use the -n or –no-verify flag with git.

Basic git command-line workflow

The following is a basic example of the git commands that can be used to contribute to the code.

# create your own fork of scikit-rf in the GitHub interface, say ME/scikit-rf

# clone your new fork locally, using either:
git clone ME@github.com:ME/scikit-rf.git

# if you have ssh keys setup, or if not:
git clone https://github.com/scikit-rf/scikit-rf.git

# ... make your changes...

# commit changes locally
git commit -a

# push changes to your repo
git push origin

# create a pull request on github.com

Staying Synchronized

To keep your local version synchronized (up-to-date) with the scikit-rf repository, add a “remote” (call it “upstream”). From this remote, you can “fetch” and “merge” the official scikit-rf repo’s changes into your local repo.

git remote add upstream https://github.com/scikit-rf/scikit-rf.git

# Fetch any new changes from the original repo
git fetch upstream

# Merges any changes fetched into your working files
git merge upstream/master

Tests

Tests are vital for software reliability and maintainability. Writing tests often require additional effort but saves time in the long run. Tests enable us to quickly discover when we introduce new errors. It is also a way to provide examples of how functions and classes were originally intended to be used.

Before making a Pull Request, we advise contributors to run the tests locally to check if nothing has been broken following their modifications. In addition, we highly recommend providing new tests when adding new features.

The structure of the testing generally follows the conventions of numpy/scipy. Test cases live in the module, or submodule, which they are testing, and are located in a directory called tests. So, the tests of the media module are located at skrf/media/tests/. Tests can be run most easily with pytest.

You probably don’t want to run the tests for the virtual instruments skrf.vi with the rest of the tests, so these tests are excluded by default.

To run all the tests (except the virtual instruments)

cd scikit-rf
pytest

Or, to run tests for every installed Python installation in an isolated environment.

tox

To run all tests and all tutorials and example notebooks (recommended before making a pull request):

tox -- --nbval-lax

If you want to test a single file or directory, you need to override the default pytest configuration (defined in the tox.ini file) and indicate the test path. For example, to run only the tests associated with the Network object (-v to increase the verbosity):

pytest -v -c "" skrf/tests/test_network.py

It is also possible to select some particular tests using the regex option (-k):

pytest -v -c "" skrf/calibration/tests/test_calibration.py -k "test_error_ntwk"

Contributing to the Documentation

Examples and Tutorials

Usage examples of scikit-rf are welcomed, especially when adding new features. We are using Jupyter Notebooks to write the examples and the tutorials, which are located in the scikit-rf/docs/source/examples/ and doc/source/examples directories. These notebooks are then converted into webpages with the sphinx extension called nbsphinx.

The docs are automatically built and served by readthedocs when a Pull Request is accepted. The Python package requirements to build the docs are kept in scikit-rf/pyproject.toml.

Important

Before pushing to your repo and making a pull request, at a minimum you will need to clear the notebook outputs using the “Clear All Output” command in the notebook (or install nbstripout so that the output is not tracked in git (or the repo size would grow infinitely).

Reference (API) or static documentation

The documentation source files can be found in doc/source/.

The reference documentation for the functions, classes, and submodules are documented in docstrings following the conventions put forth by Numpy/Scipy docstring format. The documentation as a whole is generated using sphinx, and written using reStructed (.rst) Text.

Tip

If you want to write some .rst file yourself, please use an RST format editor and checker (ex: https://livesphinx.herokuapp.com/), as Sphinx is (very) picky with the syntax…

Building the documentation locally

Before making a pull request concerning the documentation, it is a good idea to test locally if your changes lead to the desired HTML output (sometimes some problems can arise during the conversion to HTML). The documentation is built by the following commands:

# be sure to be in the scikit-rf/doc directory
make html

The built docs then reside in doc/build/html.

Join the scikit-rf team!

Do you like using scikit-rf? Merchandise is available for you to express your love.

https://raw.githubusercontent.com/scikit-rf/scikit-rf/master/logo/skrfshirtwhite.png