CONTRIBUTING.rst

Overall Guidelines

Bug reports, feature suggestions and pull requests welcome (on GitHub). Security issues should be reported by email to the core developers (emails available in the "Author" field of commits in the Git history).

When editing please don't reformat code—this makes diffs and pull requests hard to read.

Code should be flake8-clean and the test coverage is and should remain 100%. Add new tests whenever you add new features.

Hints on Development

Python version support in the current master branch may differ from the latest release in PyPI. Please inspect .travis.yml or run python setup.py --classifiers to see which versions of Python are supported in the current master branch.

Installing dependencies and running tests can be done with:

python setup.py test

The documentation can be generated and viewed with:

pip install sphinx
python setup.py build_sphinx
firefox docs/_build/html/index.html

The documentation is generated from docstrings within *.py files, and *.rst documentation files in the docs/ directory.

You can develop against multiple versions of Python using virtualenv:

python3 -m venv .virtual-py3 && source .virtual-py3/bin/activate
pip install -r requirements.txt -r tests/requirements.txt

and

virtualenv -p python2 --no-site-packages .virtual-py2 && source .virtual-py2/bin/activate
pip install -r requirements.txt -r tests/requirements.txt

After making changes, run pytest in all virtualenvs:

source .virtual-py3/bin/activate
pytest

source .virtual-py2/bin/activate
pytest

Installation should be as simple as:

python setup.py install

Editing the logo

The logo is available as an SVG file in assets/. You may need to install the Open Sans and Zilla Slab fonts (download and store the *.ttf files in your ~/.local/share/fonts directory) to view it properly. The file can then be opened in e.g. Inkscape.

Release Checklist

Releases can be done only by people with sufficient privileges on GitHub and PyPI. Things to do are:

At each release:

• Make all final changes to the repository before release:

  • Document all notable changes in docs/ChangeLog.rst.
  • Update the version number to X.Y.Z in mechanicalsoup/__version__.py.
  • Remove the (in development) mention in docs/ChangeLog.rst.

• Commit and push the release to GitHub (both branch and tag):

  git commit -m "Release X.Y.Z"
  git branch vX.Y
  git tag vX.Y.Z
  git push origin master vX.Y vX.Y.Z
  

• Visit the release page on GitHub, copy the relevant section from docs/ChangeLog.rst to the release page.

• Upload the distribution (see the Python Packaging Guide for details). First, install any needed dependencies:

  pip install --upgrade setuptools wheel twine
  

  Then locally prepare the distribution:

  python setup.py sdist bdist_wheel
  

  Use the following ~/.pypirc (if you omit the username and password fields for security, you will be prompted for them during the upload):

  [distutils]
  index-servers =
      pypi
      test
  
  [test]
  repository = https://test.pypi.org/legacy/
  username = <username>
  password = <password>
  
  [pypi]
  repository = https://upload.pypi.org/legacy/
  username = <username>
  password = <password>
  

  Upload the distribution to Test PyPI:

  twine upload -r test dist/*
  

  Once you verify that it is correct on test.pypi.org and make any necessary fixes for the official distribution, you are ready to release:

  twine upload -r pypi dist/*
  

• Check on https://pypi.org/project/MechanicalSoup/, and verify installation from PyPI with pip install --no-cache-dir mechanicalsoup.

Right after the release:

• Update the version number to a X.Y.Z-dev number in mechanicalsoup/__version__.py
• Create a new (in development) section in docs/ChangeLog.rst.
• git commit -m "Prepare for next release" && git push