How to publish your code#

This is a step by step guide for turning your code into a Python package.

Creating a package#

Create a repository just for the code#

Often you will develop the software in tandem with a paper. When publishing the source code you will not want to make public the complete history of the paper-writing process, so you should create a new repository that will contain just your code.

  • Create a new repository in the qt group of the Kwant Gitlab.

  • Clone the new (empty) repository onto your machine

Add basic files#

You should use the new-project template, which adds the following files, modifying their contents as necessary

  • LICENSE: Copy the contents of an appropriate license. The 3-clause BSD license is a reasonable choice. Set the copyright holder to <your package name> authors.

  • AUTHORS.md

  • README.md: The package name and a short description

  • .gitignore

Commit these files.

Add Code#

  • Create a directory with the same name as your package, and put an __init__.py file into it.

  • Run the following: curl https://raw.githubusercontent.com/jbweston/miniver/master/install-miniver | python - <your_package_name>, substituting <your_package_name> appropriately. This will add a line to your __init__.py, and create some files for dealing with versioning.

  • Put this setup.py in your repository root, modifying as appropriate.

  • Add your code into the package directory. Any tutorial notebooks can stay in the repository root.

Commit all the files that were just added, including the files that were added by the shell command in step 2.

Creating a Release#

Tag the release#

  • Make sure that the repository is clean (git status shows no uncommitted or untracked files)

  • Tag the release git tag -a v<MAJOR>.<MINOR>.<PATCH> -m '<MESSAGE>'. Generally you should bump the major version if you introduce breaking changes, the minor version if you add new features, and the patch version if you just fix bugs.

  • The first time you can use v1.0.0

Test installation#

  • Create a conda environment to use for testing, e.g. conda create -n test-env python=3.6 && source activate test-env

  • python setup.py install

  • Test that the package is importable: cd /tmp ; python -c 'import <package>; print(<package>.__version__)' ; cd - should print the package version, with no trailing -dirty or anything

  • You should also take this opportunity to test that the installed package passes all its unit tests.

Create source and binary distributions#

  • rm -r dist && python setup.py sdist bdist_wheel

  • dist/ should now contain .tar.gz file and a .whl file. The version string should be in the filenames.

  • inspect the contents of the .tar.gz file to make sure that you didn’t include any random cruft

Publish the code on PyPI#

  • Create an account on https://pypi.org/ if you don’t have one

  • pip install twine. This is the PyPI upload tool

  • twine upload dist/* to upload the previously created source and binary distributions to PyPI

Obtain a DOI from Zenodo#

  • Create an account in Zenodo and click to upload a new file. You do not need to add the files right away, rather just fill in the necessary parts to obtain a DOI and save your progress.

  • Test your code in binder to make sure other people will be able to run it and (hopefully) not suffer. To do this do the following:

    • Create a github public repository with a “README.txt” file.

    • Add, commit and push your code to the repository.

    • Add, commit and push a file to specify the Python environment necessary to run your code. This means that you need to include all the libraries and (if necessary) their versions. Call this file “ENVIRONMENT.yml”. An example of such a file looks like this:

    name: name-of-my-cool-environment
    channels:
      - conda-forge
    dependencies:
      - python==3.9.*
      - jupytext
      - svgutils
      - kwant==1.4.*
      - pip
      - pip:
        - ipynb
    
    • Go to binder and use the repo’s link to test that everything works as wished.

  • Download the repository, compress it as a zip and upload it to Zenodo. It is important that you compress your code as a zip so Zenodo and binder can work together.

  • Publish your code. Do this only if everything is awesome, because otherwise you will have to upload a new version to Zenodo.