Add contribution guide, code of conduct, authors file, and pull reque…

…st template (#6)

* Add contribution guide

* Add ``AUTHORS.rst``

* Add code of conduct

* Add pull request template

* Make docs use version in `uplink.__about__`

* Update contribution guide

* Update README

* Update preview note on documentation homepage

* Bump patch version

* Update changelog

* Update CONTRIBUTING.rst

* Update AUTHORS.rst

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,8 @@
+Fixes # .
+
+Changes proposed in this pull request:
+-
+-
+-
+
+Attention: @prkumar

AUTHORS.rst

@@ -0,0 +1,6 @@
+Maintainers
+***********
+- Raj Kumar (`@prkumar <https://github.com/prkumar>`_)
+
+Contributors
+************

CHANGELOG.rst

@@ -6,9 +6,24 @@ All notable changes to this project will be documented in this file.
 The format is based on `Keep a Changelog`_, and this project adheres to the
 `Semantic Versioning`_ scheme.
 
+0.1.1_ - 2017-10-21
+===================
+Added
+-----
+- Contribution guide, ``CONTRIBUTING.rst``.
+- "Contributing" Section in README.rst that links to contribution guide.
+- ``AUTHORS.rst`` file for listing project contributors.
+- Adopt `Contributor Covenant Code of Conduct`_.
+
+.. _`Contributor Covenant Code of Conduct`: https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
+
+Changed
+-------
+- Replaced tentative contributing instructions in preview notice on
+  documentation homepage with link to contribution guide.
+
 0.1.0 - 2017-10-19
 ==================
-
 Added
 -----
 - Python ports for almost all method and argument annotations in Retrofit_.
@@ -24,4 +39,6 @@ Added
 
 .. _Retrofit: http://square.github.io/retrofit/
 .. _`Keep a Changelog`: http://keepachangelog.com/en/1.0.0/
-.. _`Semantic Versioning`: https://packaging.python.org/tutorials/distributing-packages/#semantic-versioning-preferred
+.. _`Semantic Versioning`: https://packaging.python.org/tutorials/distributing-packages/#semantic-versioning-preferred
+
+.. _0.1.1: https://github.com/olivierlacan/keep-a-changelog/compare/v0.1.0...v0.1.1

CODE_OF_CONDUCT.md

@@ -0,0 +1,73 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, gender identity and expression, level of experience,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or
+  advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the project team at raj.pritvi.kumar@gmail.com. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. The project team is
+obligated to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
+available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
+
+[homepage]: https://www.contributor-covenant.org

CONTRIBUTING.rst

@@ -0,0 +1,196 @@
+How to Contribute to Uplink
+***************************
+
+The following is a guide for contributing to Uplink. Thanks for taking the
+time to improve an open source project!
+
+This guide is a work in progress. So, if you have suggestions for
+improving the contributors' experience, the release process, or really
+anything concerning the source code's management, please feel free to
+contact `@prkumar <https://github.com/prkumar>`_ directly.
+
+Reporting Bugs and Making Feature Requests
+==========================================
+
+We use the GitHub issue tracker for wrangling bug reports and feature requests.
+Before you open an issue, please do a quick search against both **closed and
+open** issues to ensure that the defect or feature request has not been
+reported already.
+
+Feature Requests
+----------------
+As the project is in initial development, we are accepting feature request!
+To request a feature, open a GitHub issue, summarize the enhancement, and add
+the "feature request" label!
+
+Making Changes to the Source
+============================
+
+Changes to the source code typically address one of the following:
+
+* `Feature enhancement or minor bug fix`_
+* `Critical bug fix`_
+
+And, a unit of development typically follows this workflow:
+
+1. Fork the repository if you don't have write-access.
+2. Make your changes, adhering to the `style guide`_.
+3. Add or update testing_.
+4. Update documentation, if necessary.
+5. Add yourself to AUTHORS.rst.
+6. When your changes are ready for review, open a `pull request`_.
+7. Merge changes.
+
+Development Process
+===================
+
+In this section, we'll outline the various development stages of Uplink.
+Moreover, we use the GitFlow branching model for Uplink, and as the development
+process and branching model go hand-in-hand, we'll cover how GitFlow ties into
+each stage.
+
+To start off, we'll cover the two, everlasting branches: ``master`` and
+``develop``.
+
+``master``
+----------
+
+This branch is the most stable branch. Nominally, ``master``
+strictly contains merge commits, each tagged with a release version (e.g,
+``v0.1.0``). See releases_ for more on how we handle the releasing
+process.
+
+You can read about the `master branch
+<http://nviecom/posts/a-successful-git-branching -model/#the-main-branches>`_
+in the linked GitFlow article.
+
+``develop``
+-----------
+
+This branch contains work-in-progress for the next immediate release.
+You can read about the `develop branch
+<http://nviecom/posts/a-successful-git-branching -model/#the-main-branches>`_
+in the linked GitFlow article..
+
+Feature Enhancement or Minor Bug Fix
+------------------------------------
+
+Subject to inclusion in some future release, features are logically cohesive
+units of work that add value to Uplink. In like manner, a
+non-critical bug fix adds value in that it addresses a value destroying
+characteristic of the code, a defect. Further, a minor bug is a
+defect that we can wait to patch in a different version. A defect that
+requires immediate attention needs a `critical bug fix`_.
+
+Development of a feature or a minor bug fix should happen on a
+feature branch, which contains work for the next or some distant
+release. Feature development typically looks like:
+
+1. Branch off of ``develop``. Preferably, prefix the branch name with
+   ``feature/`` (or ``feature/v{version}/``, where {version} is the feature's
+   target release version -- e.g., ``feature/v1.0.0/*``) for clarity.
+2. Make your changes.
+3. If your changes are not targeted for the next immediate release, keep them
+   on the feature branch until the release branch is cut (see releases_).
+4. Once you're done making changes, it's time to merge into develop:
+
+ - Substantial changes require opening a `pull request`_.
+ - Always **squash and merge**.
+
+5. If the ``develop`` branch fails the Travis CI or Coveralls builds that run
+   immediately after your feature merge, revert the squashed merge commit.
+   Address the issue locally -- i.e., go back to step 2.
+6. Delete the feature branch.
+
+You can read more about `feature branches
+<http://nvie.com/posts/a-successful-git-branching-model/#feature-branches>`_
+in the linked GitFlow article.
+
+Critical Bug Fix
+----------------
+
+To fix a critical bug that affects the latest released version of Uplink and
+requires immediate action (i.e., we can't wait and fix it in the next
+release), we'll need to:
+
+1. Create a hotfix branch off ``master``.
+2. Increment the version number.
+3. Implement a fix.
+4. Open `pull request`_ against ``develop``, and another against ``master``.
+
+You can read more about `hotfix branches
+<http://nvie.com/posts/a-successful-git-branching-model/#hotfix-branches>`_
+in the linked GitFlow article.
+
+Releases
+--------
+
+Once we're ready to begin the release process, we'll create a release branch
+off an appropriate commit of ``develop``. The name of a release branch
+should follow the pattern ``release/v{version}``, where ``{version}`` is the
+target release version number (e.g., ``release/v1.0.0``).
+
+Once the release branch is merged into ``master``, we consider the release
+completed. However, up until this point, we can make necessary changes to
+the release branch, while normal feature development continues on ``develop``.
+
+When merging the release branch into ``master``, be sure to **squash and
+merge**. After merging, create a tag named ``v{version}``, where
+``{version}`` is the target release version number (e.g., ``v1.0.0``),
+on the the merge commit in ``master``. Tagging the commit prompts Travis
+CI to deploy the latest release to PyPI.
+
+You can read more about `release branches
+<http://nvie.com/posts/a-successful-git-branching-model/#release-branches>`_
+in the linked GitFlow article. Notably, before removing a release branch, we'll
+need to merge the branch into ``develop`` to incorporate commits made after the
+release branch was cut. Moreover, once a release branch is cut, we need to bump
+the version number on ``develop``.
+
+.. _`pull request`:
+
+Pull Request
+============
+
+Depending on the type of change you are making, the branching model may
+require merging your work into one or two target branches (typically one is
+``develop``). Be sure to open a pull request for each target branch.
+
+1. Open a pull request (PR) to merge your forked branch, the
+   **candidate**, into **target** branch of this repository.
+2. Add Raj (``prkumar``) as a reviewer.
+3. If your PR fails the Travis CI check, investigate the build log for
+   cause of failure, address locally, and update the candidate branch. Repeat
+   this step until the PR passes the Travis CI check.
+4. If your PR fails the Coveralls check, check the PR's Coveralls' report
+   to identify modules experiencing a test coverage drop. Improve testing
+   locally, then update the candidate branch.
+5. Once all checks have passed and the assigned reviewers have approved,
+   your changes will be **squashed and merged** into the target branch.
+
+.. _tests:
+
+Testing
+=======
+
+We use the unit testing framework ``pytest``. Kept under the `tests`
+directory, unit tests are written in Python modules with the filename
+pattern ``test_*.py``.
+
+Notably, ``conftest.py`` defines several `pytest fixtures
+<https://docs.pytest.org/en/latest/fixture.html>`_, for injecting an
+instance of an interface (defined in ``uplink.interfaces``) or utility
+(defined in ``uplink.helpers``) class into your tests.
+
+Style Guide
+===========
+
+To maintain a consistent code style with the rest of Uplink, follow the `Google
+Python Style Guide`_.
+
+Notably, we use a Sphinx plugin that can parse docstrings adherent to this
+style. Checkout `this page
+<http://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html>`_
+for examples of Google Python Style Guide docstrings.
+
+.. _`Google Python Style Guide`: https://google.github.io/styleguide/pygu

README.rst

@@ -60,18 +60,34 @@ accessing HTTP webservices, with minimal code and user pain ☺️.
 Installation
 ------------
 
-``uplink`` supports Python 2.7 & 3.3-3.7. To install the package, you can use
-``pip``:
+``uplink`` supports Python 2.7 & 3.3-3.7.
+
+To install the latest stable release, you can use ``pip``:
 
 ::
 
     $ pip install uplink
 
+
+Interested in the cutting-edge? You can install the work-in-progress for the
+upcoming release with:
+
+::
+
+   $ pip install https://github.com/prkumar/uplink/archive/develop.zip
+
 Documentation
 -------------
 
 For more details, check out the documentation at http://uplink.readthedocs.io/.
 
+Contributing
+------------
+
+Looking to report a bug, request a feature, or contribute code to Uplink?
+Checkout the `Contribution Guide <CONTRIBUTING.rst>`_ ! Thanks for taking
+the time to improve an open source project!
+
 .. |Build Status| image:: https://travis-ci.org/prkumar/uplink.svg?branch=master
    :target: https://travis-ci.org/prkumar/uplink
 .. |Coverage Status| image:: https://coveralls.io/repos/github/prkumar/uplink/badge.svg?branch=master

docs/source/conf.py

@@ -20,6 +20,8 @@
 # import sys
 # sys.path.insert(0, os.path.abspath('.'))
 
+# Import package metadata
+from uplink.__about__ import __version__
 
 # -- General configuration ------------------------------------------------
 
@@ -61,9 +63,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = u'0.1'
+version = __version__
 # The full version, including alpha/beta/rc tags.
-release = u'0.1.0'
+release = __version__
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

docs/source/index.rst

@@ -23,13 +23,11 @@ A Declarative HTTP Client for Python. Inspired by `Retrofit
    opening a GitHub issue when you notice a missing feature, latent defect,
    documentation oversight, etc.
 
-   Moreover, for those interested in contributing, I plan to publish a
-   contribution guide soon, but in the meantime, please feel free to fork
-   the `repository on GitHub <https://github.com/prkumar/uplink>`__ and open
-   a pull request ('tis
-   `Hacktoberfest <https://hacktoberfest.digitalocean.com/>`__, after all)!
+   Moreover, for those interested in contributing, checkout the `Contribution
+   Guide on GitHub`_ ('tis `Hacktoberfest`__, after all)!
 
-----
+.. _`Contribution Guide on GitHub`: https://github.com/prkumar/uplink/blob/master/CONTRIBUTING.rst
+.. _Hacktoberfest: https://hacktoberfest.digitalocean.com/
 
 A Quick Walkthrough, with GitHub API v3:
 ----------------------------------------