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 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¶
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.
Basically, you will:
Make your modifications.
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!
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
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 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 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.
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 to indicate the test path. By example, to run only the tests associated to 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
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
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
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.
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