How to Contribute

Thank you for your interest in contributing to SpyDrNet. We welcome your support and hope that you have a great experience. Additionally we hope you feel as we do that your work on SpyDrNet makes a positve impact on the greater community.

We ask all contributers to make respectful and constructive contributions in order to ensure a positive environment exists around SpyDrNet.

some suggestions as you get started

  • Make sure you have a recent version of python installed. We test against version 3.6 and up (as of SpyDrNet 1.10.0…before then we also supported Python 3.5).

  • Clone the repository and create a new branch on which to make changes.

  • Connect through Git Hub. The issues tab is the primary place for conversations and questions.

  • Make sure that there are tests for your code.

  • While we do not require 100% test coverage it is a good idea to strive to achive it.

  • Make sure that your code passes the Travis CI test before merging to master

To start contributing please follow the following steps

  1. Create a github account

  2. Clone the SpyDrNet repositoy

  3. Otherwise fork the repository to make your changes.

  4. Once you have made your changes make a pull request.

  5. When the pull request has passed the tests it will be reviewed and merged. Note: we may have you request your code into a branch other than master

Write (or other) privileges can be obtained

if

you have made a few good contributions and plan to make more

or

you are a student working on the project in the BYU CCL

and in either case

upon request to the admins who can give write privlages.

If you don’t know who the admins are and you feel that you qualify you can create an issue to request permissions.

Of course the admin’s have the final say in granting permissions and reserve the right to deny privileges for any reason or no reason at all even if the above criteria are met.

Testing

We use pytest which can be installed through pip, to test the repository. Tests are placed in the tests folders at an appropriate place in the repository. The existing tests can be used as a template to create your own and the pytest documentation can be referenced as well. Basically import unittest and then declare your class and have it inherit from the unittest.TestCase like this class TestFeatureName(unittest.TestCase): then make sure that your function is called something that starts with test_ like def test_some_functionality(self):.

Exceptions and other features can be tested as well within the pytest framework.

Creating a Release

This section aims to help you do a spydrnet release, meaning you make the latest code and documentation available. The steps are listed in what seems to be the best order of operation. Steps which need more explanation are highlighted below.

  1. Merge each contributors’ branches into one branch (the ‘next_release’ branch)

  2. run git merge master while the next-release branch is checked out.

  3. Update the Release Notes (remember to commit and push afterwards).

  4. Update the Documentation and ensure it can build properly

  5. On Github, create a pull request with the updated code in the next_release branch.

  6. Accept and merge the pull request when the checks have finished.

  7. Move to the master branch using git checkout master and run git pull

  8. Create and Update the Tag

  9. Build the Python Package (this will update the documentation’s version number)

  10. Build the Documentation

  11. Publish the Packages to Pypi

  12. Create a Github Release

  13. Publish the Documentation

Update the Release Notes

The release notes file called RELEASE.rst should be updated to outline what has been acomplished. The date and version number should be included and other information as needed can be entered as well.

SpyDrNet uses a Major.Minor.Bug versioning scheme where minor version updates do not break the existing API and major version updates may break it. Bug fixes do not add substantial new functionality, but rather fix broken functionality.

Update the Documentation

The documentation pulls from doc strings as well as .rst files in the build so this step is important. The documentation is built using a makefile in the docs folder.

Before building the documentation run make clean to clear away the old files.

Before proceeding, ensure that both of the following are successful (make they execute without errors. Try to minimize the warnings as well):

>>> make html

and

>>> make latexpdf

if you are missing packages run:

>>> make install

You may also need to run ‘sudo apt install latexmk’ and ‘apt install texlive-latex-extra’ to be able to create the pdf file.

The generated files can be found in the build folder. Take a look at them and make sure everything looks good. Later, these commands will be run again, and the html files put online and pdf files added to the Github release files.

Create and Update the Tag

Be sure you are on the master branch.

Tags are used to label the release. When all changes are merged into the main branch, create a new tag. In the examples below, replace 1.5.0 with the version number you are releasing.

To see the current version number

>>> git describe

Create the tag

>>> git tag -a v1.5.0 -m "SpyDrNet 1.5.0"

Push your changes to the tags

>>> git push --tags

If you mess up, you can use the following instructions to force update your tag

Updating

>>> git tag -a v1.5.0 -m "SpyDrNet 1.5.0" -f

>>> git push --tags -f

Build the Python Package

Refer to pypi.org if necessary. They have a tutorial called “uploading packages”

Upgrade pip if needed.

>>> python3 -m pip install --upgrade pip

Make sure everything is up to date

>>> python3 -m pip install --upgrade setuptools wheel

Make sure you are in the top level directory. Make the python archive package:

>>> python3 setup.py sdist bdist_wheel

The build files will be stored in the following directories

spydrnet/build and spydrnet/dist

Build the Documentation

Make sure you are in the docs directory

>>> cd docs

then run the following:

>>> make clean
>>> make latexpdf
>>> make html

Make sure that each one executes without errors. Try to minimize warnings as well, although the most important thing is that the documentation looks the way you want it to.

Publish the Packages to Pypi

The packages need to be published to Pypi in order to be installable via pip. On the Pypi website there is a guide on uploading packages. You will need an account for this. Follow the instructions there to upload to the test pip server and then the production server.

If you have an account and know what you are doing, use the command below :

>>> python3 -m twine upload dist/*

And then input your username and password for Pypi.

To install the python package to check for success, use:

>>> python3 -m pip install spydrnet

Then go to the release on the Pypi website through your account. Download the .whl file and the .tar.gz file. These will be used in the next step.

Create a Github Release

Releases can be created on Github. On the releases tab you can draft a new release. You can then select the existing tag with the release number you want to release.

The release should be named SpyDrNet 1.5.0 where 1.5.0 is replaced with the proper release number.

Enter a description–it could just be a reiteration of the release notes or other relevant information.

Four files should be added as assets to the new release:

  1. The .tar.gz file from the previous step

  2. The .whl file from the previous step

  3. The spydrnet_reference pdf document created in the Build the Documentation step. Go to docs/latex folder, change the spydrnet_reference.pdf name to spydrnet_reference-new_release_number.pdf, and then copy it to the assets under the new release.

  4. The pylint_output.txt

Publish the Documentation

This is easiest on Linux (or at least not Windows, MacOS works fine as well)

Make sure you are still on the Master branch and that everything in the html folder is up-to-date. If not, re-run the instructions in Build the Documentation.

Move to the gh-pages branch using

>>> git checkout gh-pages

Create a new folder with the release number as the name. Move the contents of the docs/build/html folder into the newly created folder. Then delete the html folder (which should be empty).

(If html folder doesn’t contain the latest pages, it could be that the html folder wasn’t deleted from the previous release, delete the folder, commit the changes and repeat the steps above)

The documentation is built from a stable link which will need to be updated to point to the new documentation.

Check which version of the documentation the stable link points to

>>> ls -lha

To update the stable link, remove it first (watch syntax here very carefully, a terminating could make the command delete the folder’s contents instead of the link)

>>> rm stable

Then create a link to the new folder

>>> ln -s version.number stable

Then add, commit, and push the newly created folder and the updated stable link to the git repository, just to the gh-pages branch.