Create CONTRIBUTING.rst

2016-07-16 01:35:54 -07:00
parent 246e06fad0
commit a79d249d2a
1 changed files with 108 additions and 0 deletions
--- a/CONTRIBUTING.rst
+++ b/CONTRIBUTING.rst
@@ -0,0 +1,108 @@
+-----------------------
+Contributor Guidlines
+-----------------------
+
+Before you start
+================
+
+- Post an issue on the `tracker <https://github.com/michael-lazar/rtv/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 **ABSOLUTELY CAN'T** get the tests to run, 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 pytest vcrpy
+
+2. Set your ``$PYTHONPATH`` to point to the directory of your RTV repository.
+
+    .. code-block:: bash
+
+      $ export PYTHONPATH=~/code/rtv/
+
+3. Run the tests using the existing cassettes
+  
+   .. code-block:: bash
+    
+     $ 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 *~/.config/rtv/refresh-token*.
+
+   .. code-block:: bash
+    
+      $ python -m pytest ~/code/rtv/tests/ --record-mode once --refresh-token ~/.config/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