Contributing to scikit-rf

Sponsoring the Project

It is possible to sponsor the maintainers and developpers of the scikit-rf package, using the GitHub Sponsor option (“Sponsor this project”) visible in 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 email us on the scikit-rf mailing list or join us in the scikit-rf Slack channel to get some help.

skrf uses the “Fork + Pull” collaborative development model. If this 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.

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 requires additional efforts, 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 to provide 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 nosetest.

You probably don’t want to run the tests for the virtual instruments skrf.vi with the rest of the tests, so to prevent this, also install nose-exclude via pip (pip install nose-exclude) or conda.

To run all the tests (except the virtual instruments)

cd scikit-rf
nosetests skrf -c nose.cfg

Or, to run test a single module or single test,

nosetests media/
# ...
nosetests tests/test_network.py
# ...

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/requirements.txt.

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 a 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!

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