tuir/CONTRIBUTING.rst

Before you start

• Post an issue on the tracker describing the bug or feature you would like to add

• If an issue already exists, leave a comment to let others know that you intend to work on it

Considerations

• One of the project's goals is to maintain compatibility with as many terminal emulators as possible. Please be mindful of this when designing a new feature

  • Is it compatible with both Linux and OS X?

  • Is it compatible with both Python 2 and Python 3

  • Will it work over ssh (without X11)?

  • What about terminals that don't support color? Or in those with limited (8/256) colors?

  • Will it work in tmux/screen?

  • Will is fail gracefully if unicode is not supported?

• If you're adding a new feature, try to include a few test cases. See the section below on setting up your test environment

• If you tried, but you can't get the tests running in your environment, it's ok

• If you are unsure about anything, ask!

Submitting a pull request

• Reference the issue # that the pull request is related to

• Make sure you have merged in the latest changes from the master branch

• After you submit, make sure that the Travis-CI build passes

• Be prepared to have your code reviewed. For non-trivial additions, it's normal for this process to take a few iterations

Style guide

• All code should follow PEP 8

• Try to keep lines under 80 characters, but don't sacrifice readability to do it!

  Ugly

  text = ''.join(
      line for line in fp2 if not line.startswith('#'))

  Better

  text = ''.join(line for line in fp2 if not line.startswith('#'))

• Use the existing codebase as a reference when writing docstrings (adopted from the Google Style Guide)

• Add an encoding header # -*- coding: utf-8 -*- to all new files

• Please don't submit pull requests for style-only code changes

Running the tests

This project uses pytest and VCR.py

VCR is a tool that records HTTP requests made during the test run and stores them in tests/cassettes for subsequent runs. This both speeds up the tests and helps to maintain consistency across runs.

1. Install the test dependencies

   $ pip install rtv[test]

2. Set your $PYTHONPATH to point to the directory of your RTV repository.

   $ export PYTHONPATH=~/code/rtv/

3. Run the tests using the existing cassettes

   $ python -m pytest ~/code/rtv/tests/
   ================================ test session starts ================================
   platform linux -- Python 3.4.0, pytest-2.9.2, py-1.4.31, pluggy-0.3.1
   rootdir: ~/code/rtv/, inifile:
   plugins: xdist-1.14, cov-2.2.0
   collected 113 items

4. By default, the cassettes will act as read-only. If you have written a new test and would like to record a cassette, you must provide your own refresh token. The easiest thing to do is to use the token generated by RTV when you log in. This is usually stored as ~/.local/share/rtv/refresh-token.

   $ python -m pytest ~/code/rtv/tests/ --record-mode once --refresh-token ~/.local/share/rtv/refresh-token
   ================================ test session starts ================================
   platform linux -- Python 3.4.0, pytest-2.9.2, py-1.4.31, pluggy-0.3.1
   rootdir: ~/code/rtv/, inifile:
   plugins: xdist-1.14, cov-2.2.0
   collected 113 items

   Note that all sensitive information will automatically be stripped from the cassette when it's saved.

5. Once you have generated a new cassette, go ahead and commit it to your branch along with your test case