Merge pull request #49 from aoberoi/issue-30

adds contributing and development guidelines, fixes #30

Author: aoberoi

CONTRIBUTING.md

@@ -0,0 +1,47 @@
+# Contributing Guidelines
+
+For anyone looking to get involved to this project, we are glad to hear from you. Here are a few types of contributions
+that we would be interested in hearing about.
+
+*  Bug fixes
+    -  If you find a bug, please first report it using Github Issues.
+    -  Issues that have already been identified as a bug will be labelled `bug`.
+    -  If you'd like to submit a fix for a bug, send a Pull Request from your own fork and mention the Issue number.
+        +  Include a test that isolates the bug and verifies that it was fixed.
+*  New Features
+    -  If you'd like to accomplish something in the library that it doesn't already do, describe the problem in a new
+       Github Issue.
+    -  Issues that have been identified as a feature request will be labelled `enhancement`.
+    -  If you'd like to implement the new feature, please wait for feedback from the project maintainers before spending
+       too much time writing the code. In some cases, `enhancement`s may not align well with the project objectives at
+       the time.
+*  Tests, Documentation, Miscellaneous
+    -  If you think the test coverage could be improved, the documentation could be clearer, you've got an alternative
+       implementation of something that may have more advantages, or any other change we would still be glad hear about
+       it.
+       -  If its a trivial change, go ahead and send a Pull Request with the changes you have in mind
+       -  If not, open a Github Issue to discuss the idea first.
+
+## Requirements
+
+For a contribution to be accepted:
+
+*  The test suite must be complete and pass
+*  Code must follow existing styling conventions
+*  Commit messages must be descriptive. Related issues should be mentioned by number.
+
+If the contribution doesn't meet these criteria, a maintainer will discuss it with you on the Issue. You can still
+continue to add more commits to the branch you have sent the Pull Request from.
+
+## How To
+
+1. Fork this repository on GitHub.
+1. Clone/fetch your fork to your local development machine.
+1. Create a new branch (e.g. `issue-12`, `feat.add_foo`, etc) and check it out.
+1. Make your changes and commit them. (Did the tests pass?)
+1. Push your new branch to your fork. (e.g. `git push myname issue-12`)
+1. Open a Pull Request from your new branch to the original fork's `master` branch.
+
+## Developer Guidelines
+
+See DEVELOPING.md for guidelines for developing this project.

DEVELOPING.md

@@ -0,0 +1,99 @@
+# Development Guidelines
+
+This document describes tools, tasks and workflow that one needs to be familiar with in order to effectively maintain
+this project. If you use this package within your own software as is but don't plan on modifying it, this guide is
+**not** for you.
+
+## Tools
+
+*  [Pip](https://pip.pypa.io/): a command line package installer for Python. This tool is typically
+   included with recent versions of Python.
+
+*  [virtualenv](https://virtualenv.pypa.io/): a tool to create isolated Python environments. The
+   first thing you should do once you've cloned this repository is to run `pip install virtualenv;
+   virtualenv venv; source venv/bin/activate` to create an environment and load it in your shell.
+   This helps keep all the python packages you install and use isolated into a project specific
+   location on your system, which helps keep you out of dependency hell. You can exit the
+   environment using `$ deactivate`.
+
+*  [tox](https://testrun.org/tox/): a testing automation tool that can load many Python versions.
+   This tool allows the project to test against all the compatible versions of Python by leveraging
+   virtualenv and describing the tasks in a metadata file.
+
+## Tasks
+
+### Building
+
+Building isn't necessarily required for a python package, but it is possible. By running the command
+`$ python setup.py build`, an installable package will be placed in the `build/` directory.
+
+A more useful command is `$ python setup.py develop` which will make the package importable from any
+other script in your environment, and continue to update and you make changes.
+
+### Testing
+
+This project's tests are kicked off by tox. The `tox.ini` file describes the automation. In
+a nutshell, it selects a Python version, installs test dependencies stored in
+`test_requirements.txt`, and then runs `nosetests`. [Nose](https://nose.readthedocs.org) is the
+actual test runner. All of this can be ran using the following command: `$ tox`
+
+### Generating Documentation
+
+**TODO**
+
+### Releasing
+
+In order to create a release, the following should be completed in order.
+
+1. Ensure all tests are passing (`tox`) and that there is enough test coverage.
+1. Make sure you are on the `master` branch of the repository, with all changes merged/committed already.
+1. Update the version number in the source code (`opentok/version.py`) and the README. See [Versioning](#versioning) for
+   information about selecting an appropriate version number.
+1. Commit the version number change with the message ("Update to version v.x.x.x"), substituting the new version number.
+1. Create a git tag: `git tag -a vx.y.z -m "Release vx.y.z"`
+1. Ensure you have permission to update the `opentok` package on PyPI: <https://pypi.python.org/pypi/opentok>.
+1. Run `python setup.py sdist upload`, which will build and upload the package to PyPI.
+1. Change the version number for future development by adding "a1", then make another commit with the message
+   "Beginning development on next version".
+1. Push the changes to the main repository (`git push origin master`).
+1. Upload the `dist/opentok-x.y.z.tar.gz` file to the
+   [Github Releases](https://github.com/opentok/opentok-python-sdk/releases) page with a description and release notes.
+
+## Workflow
+
+### Versioning
+
+The project uses [semantic versioning](http://semver.org/) as a policy for incrementing version numbers. For planned
+work that will go into a future version, there should be a Milestone created in the Github Issues named with the version
+number (e.g. "v2.2.1").
+
+During development the version number should end in "a1" or "bx", where x is an increasing number starting
+from 1.
+
+### Branches
+
+*  `master` - the main development branch.
+*  `feat.foo` - feature branches. these are used for longer running tasks that cannot be accomplished in one commit.
+   once merged into master, these branches should be deleted.
+*  `vx.x.x` - if development for a future version/milestone has begun while master is working towards a sooner
+   release, this is the naming scheme for that branch. once merged into master, these branches should be deleted.
+
+### Tags
+
+*  `vx.x.x` - commits are tagged with a final version number during release.
+
+### Issues
+
+Issues are labelled to help track their progress within the pipeline.
+
+*  no label - these issues have not been triaged.
+*  `bug` - confirmed bug. aim to have a test case that reproduces the defect.
+*  `enhancement` - contains details/discussion of a new feature. it may not yet be approved or placed into a
+   release/milestone.
+*  `wontfix` - closed issues that were never addressed.
+*  `duplicate` - closed issue that is the same to another referenced issue.
+*  `question` - purely for discussion
+
+### Management
+
+When in doubt, find the maintainers and ask.