----------------------
Contributor Guidelines
----------------------

Before you start
================

- Post an issue on the `tracker <https://github.com/tildeclub/ttrv/issues>`_ 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 <https://www.python.org/dev/peps/pep-0008/>`_
- Try to keep lines under 80 characters, but don't sacrifice readability to do it!

  **Ugly**

  .. code-block:: python

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

  .. code-block:: python

            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 <https://google.github.io/styleguide/pyguide.html#Comments>`_)
- 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 <http://pytest.org/>`_ and `VCR.py <https://vcrpy.readthedocs.org/>`_

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

   .. code-block:: bash
  
      $ pip install ttrv[test]

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

    .. code-block:: bash

      $ export PYTHONPATH=~/code/ttrv/

3. Run the tests using the existing cassettes
  
   .. code-block:: bash
    
     $ python -m pytest ~/code/ttrv/tests/
     ================================ test session starts ================================
     platform linux -- Python 3.4.0, pytest-2.9.2, py-1.4.31, pluggy-0.3.1
     rootdir: ~/code/ttrv/, 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 ttrv when you log in.
   This is usually stored as *~/.local/share/ttrv/refresh-token*.

   .. code-block:: bash
    
      $ python -m pytest ~/code/ttrv/tests/ --record-mode once --refresh-token ~/.local/share/ttrv/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/ttrv/, 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