mirror of https://github.com/tildeclub/ttrv.git
109 lines
4.1 KiB
ReStructuredText
109 lines
4.1 KiB
ReStructuredText
----------------------
|
|
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
|