So you want to help out? Awesome. Go you!

Code of Conduct

Everyone interacting in the bandersnatch project’s codebases, issue trackers, chat rooms, and mailing lists is expected to follow the PSF Code of Conduct.

Getting Started

Bandersnatch is developed using the GitHub Flow

Pre Install

Please make sure you system has the following:

  • Python 3.8.0 or greater

  • git client

Checkout bandersnatch

Lets now cd to where we want the code and clone the repo:

  • cd somewhere

  • git clone

Development venv

One way to develop and install all the dependencies of bandersnatch is to use a venv.

  • First create one and upgrade pip

python3 -m venv /path/to/venv
/path/to/venv/bin/pip install --upgrade pip

For example:

$ python3 -m venv bandersnatchvenv
$ bandersnatchvenv/bin/pip install --upgrade pip
Collecting pip
  Using cached
Installing collected packages: pip
  Found existing installation: pip 9.0.3
    Uninstalling pip-9.0.3:
      Successfully uninstalled pip-9.0.3
Successfully installed pip-10.0.1
  • Then install the dependencies to the venv:

/path/to/venv/bin/pip install -r requirements.txt -r test-requirements.txt

For example:

$ bandersnatchvenv/bin/pip install -r requirements.txt -r test-requirements.txt
Collecting six==1.10.0 (from -r requirements.txt (line 2))
Collecting pyparsing==2.1.10 (from -r requirements.txt (line 3))
  Downloading (56kB)
    100% |████████████████████████████████| 61kB 2.3MB/s
Collecting python-dateutil==2.6.0 (from -r requirements.txt (line 4))
  Downloading (194kB)
    100% |████████████████████████████████| 194kB 1.3MB/s
Collecting packaging==16.8 (from -r requirements.txt (line 5))
Collecting requests==2.12.4 (from -r requirements.txt (line 6))
  Downloading (576kB)
    100% |████████████████████████████████| 583kB 3.2MB/s
Collecting xmlrpc2==0.3.1 (from -r requirements.txt (line 7))
Collecting bandersnatch==2.1.3 (from -r requirements.txt (line 8))
Collecting flake8 (from -r test-requirements.txt (line 1))
  Downloading (69kB)
    100% |████████████████████████████████| 71kB 4.8MB/s
Collecting pep8 (from -r test-requirements.txt (line 2))
  Downloading (41kB)
    100% |████████████████████████████████| 51kB 9.6MB/s
Collecting pytest (from -r test-requirements.txt (line 3))
  Downloading (192kB)
    100% |████████████████████████████████| 194kB 2.8MB/s
Collecting pytest-codecheckers (from -r test-requirements.txt (line 4))
Collecting pytest-cov (from -r test-requirements.txt (line 5))
Collecting pytest-timeout (from -r test-requirements.txt (line 6))
Collecting pytest-cache (from -r test-requirements.txt (line 7))
Requirement already satisfied: setuptools in /private/tmp/bandersnatchvenv/lib/python3.6/site-packages (from -r test-requirements.txt (line 8)) (39.0.1)
Collecting tox (from -r test-requirements.txt (line 9))
  Downloading (60kB)
    100% |████████████████████████████████| 61kB 2.2MB/s
Collecting pycodestyle<2.4.0,>=2.0.0 (from flake8->-r test-requirements.txt (line 1))
  Downloading (45kB)
    100% |████████████████████████████████| 51kB 4.4MB/s
Collecting mccabe<0.7.0,>=0.6.0 (from flake8->-r test-requirements.txt (line 1))
Collecting pyflakes<1.7.0,>=1.5.0 (from flake8->-r test-requirements.txt (line 1))
  Downloading (227kB)
    100% |████████████████████████████████| 235kB 2.6MB/s
Collecting py>=1.5.0 (from pytest->-r test-requirements.txt (line 3))
  Downloading (84kB)
    100% |████████████████████████████████| 92kB 3.8MB/s
Collecting pluggy<0.7,>=0.5 (from pytest->-r test-requirements.txt (line 3))
Collecting more-itertools>=4.0.0 (from pytest->-r test-requirements.txt (line 3))
  Downloading (47kB)
    100% |████████████████████████████████| 51kB 3.9MB/s
Collecting attrs>=17.4.0 (from pytest->-r test-requirements.txt (line 3))
Collecting coverage>=3.7.1 (from pytest-cov->-r test-requirements.txt (line 5))
  Downloading (178kB)
    100% |████████████████████████████████| 184kB 3.3MB/s
Collecting execnet>=1.1.dev1 (from pytest-cache->-r test-requirements.txt (line 7))
Collecting virtualenv>=1.11.2 (from tox->-r test-requirements.txt (line 9))
  Downloading (2.6MB)
    100% |████████████████████████████████| 2.6MB 3.3MB/s
Collecting apipkg>=1.4 (from execnet>=1.1.dev1->pytest-cache->-r test-requirements.txt (line 7))
Installing collected packages: six, pyparsing, python-dateutil, packaging, requests, xmlrpc2, bandersnatch, pycodestyle, mccabe, pyflakes, flake8, pep8, py, pluggy, more-itertools, attrs, pytest, pytest-codecheckers, coverage, pytest-cov, pytest-timeout, apipkg, execnet, pytest-cache, virtualenv, tox
  Running install for pytest-codecheckers ... done
  Running install for pytest-cache ... done
Successfully installed apipkg-1.4 attrs-18.1.0 bandersnatch-2.1.3 coverage-4.5.1 execnet-1.5.0 flake8-3.5.0 mccabe-0.6.1 more-itertools-4.1.0 packaging-16.8 pep8-1.7.1 pluggy-0.6.0 py-1.5.3 pycodestyle-2.3.1 pyflakes-1.6.0 pyparsing-2.1.10 pytest-3.5.1 pytest-cache-1.0 pytest-codecheckers-0.2 pytest-cov-2.5.1 pytest-timeout-1.2.1 python-dateutil-2.6.0 requests-2.12.4 six-1.10.0 tox-3.0.0 virtualenv-15.2.0 xmlrpc2-0.3.1
  • Finally install bandersnatch in editable mode:

/path/to/venv/bin/pip install -e .

Creating a Pull Request

Changelog entry

PRs must have an entry in that references the PR number in the format of “PR #{number}”. You can get the number your PR will be assigned beforehand using Next PR Number. Some trival changes (eg. typo fixes) won’t need an entry, but most of the time, your change will. If unsure, take a look at what’s been logged before or just add one to be safe.

This is enforced by a GitHub Actions workflow.

Running Bandersnatch

You will need to customize src/bandersnatch/default.conf and run via the following:

WARNING: Bandersnatch will go off and sync from and use large amounts of disk space!

cd bandersnatch
/path/to/venv/bin/pip install --upgrade .
/path/to/venv/bin/bandersnatch -c src/bandersnatch/default.conf mirror

Running Unit Tests

We use tox to run tests. tox.ini has the options needed, so running tests is very easy.

cd bandersnatch
/path/to/venv/bin/tox [-vv]

Example output:

$ tox
GLOB sdist-make: /Users/dhubbard/PycharmProjects/bandersnatch/
py36 create: /Users/dhubbard/PycharmProjects/bandersnatch/.tox/py36
py36 installdeps: -rtest-requirements.txt
py36 inst: /Users/dhubbard/PycharmProjects/bandersnatch/.tox/dist/
py36 installed: apipkg==1.4,attrs==18.1.0,bandersnatch==2.2.1,certifi==2018.4.16,chardet==3.0.4,coverage==4.5.1,execnet==1.5.0,flake8==3.5.0,idna==2.6,mccabe==0.6.1,more-itertools==4.1.0,packaging==17.1,pep8==1.7.1,pluggy==0.6.0,py==1.5.3,pycodestyle==2.3.1,pyflakes==1.6.0,pyparsing==2.2.0,pytest==3.5.1,pytest-cache==1.0,pytest-codecheckers==0.2,pytest-cov==2.5.1,pytest-timeout==1.2.1,python-dateutil==2.7.3,requests==2.18.4,six==1.11.0,tox==3.0.0,urllib3==1.22,virtualenv==15.2.0,xmlrpc2==0.3.1
py36 runtests: PYTHONHASHSEED='42669967'
py36 runtests: commands[0] | pytest
========================================================================================================================= test session starts =========================================================================================================================
platform darwin -- Python 3.6.5, pytest-3.5.1, py-1.5.3, pluggy-0.6.0
rootdir: /Users/dhubbard/PycharmProjects/bandersnatch, inifile: pytest.ini
plugins: timeout-1.2.1, cov-2.5.1, codecheckers-0.2
timeout: 10.0s method: signal
collected 94 items

src/bandersnatch/ ..                                                                                                                                                                                                                                 [  2%]
src/bandersnatch/ ..                                                                                                                                                                                                                                 [  4%]
src/bandersnatch/ ..                                                                                                                                                                                                                                      [  6%]
src/bandersnatch/ ..                                                                                                                                                                                                                                     [  8%]
src/bandersnatch/ ..                                                                                                                                                                                                                                   [ 10%]
src/bandersnatch/ ..                                                                                                                                                                                                                                   [ 12%]
src/bandersnatch/ ..                                                                                                                                                                                                                                  [ 14%]
src/bandersnatch/ ..                                                                                                                                                                                                                                  [ 17%]
src/bandersnatch/ ..                                                                                                                                                                                                                                    [ 19%]
src/bandersnatch/tests/ ..                                                                                                                                                                                                                           [ 21%]
src/bandersnatch/tests/ .......                                                                                                                                                                                                                     [ 28%]
src/bandersnatch/tests/ ...........                                                                                                                                                                                                               [ 40%]
src/bandersnatch/tests/ ....................                                                                                                                                                                                                      [ 61%]
src/bandersnatch/tests/ ..............................                                                                                                                                                                                           [ 93%]
src/bandersnatch/tests/ ......                                                                                                                                                                                                                     [100%]

---------- coverage: platform darwin, python 3.6.5-final-0 -----------
Coverage HTML written to dir htmlcov

====================================================================================================================== 94 passed in 3.40 seconds ======================================================================================================================
_______________________________________________________________________________________________________________________________ summary _______________________________________________________________________________________________________________________________
  py36: commands succeeded
  congratulations :)

You want to see:

py3: commands succeeded
congratulations :)

Making a release

Please rely on GitHub actions to cut a release.

To do so, make a GitHub Release and GitHub Actions will package and upload to PyPI.