Template updates

.github/ISSUE_TEMPLATE.md

@@ -1,5 +1,23 @@
-Please include the following information in your ticket.
+Please [read these guidelines](http://ibm.biz/cdt-issue-guide) before opening an issue.
 
-- Cloudant (python-cloudant) version(s) that are affected by this issue.
-- Python version 
-- A small code sample that demonstrates the issue.
+<!-- Issues will be CLOSED IMMEDIATELY if the following template is not completed. -->
+
+## Bug Description
+
+### 1. Steps to reproduce and the simplest code sample possible to demonstrate the issue
+<!--
+Outline the steps you take to make the problem happen.
+Provide the simplest code sample you can, in context, that reproduces the issue.
+-->
+
+### 2. What you expected to happen
+
+### 3. What actually happened
+
+## Environment details
+<!--
+- Version(s) that are affected by this issue.
+    > 2.0.2
+- Python version
+    > 3.6.2
+-->

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,23 +1,102 @@
+<!--
 Thanks for your hard work, please ensure all items are complete before opening.
+-->
+## Checklist
 
-- [ ] Tick to sign-off your agreement to the [Developer Certificate of Origin (DCO) 1.1](https://github.com/cloudant/python-cloudant/blob/master/DCO1.1.txt)
-- [ ] You have added tests for any code changes
-- [ ] You have updated the [CHANGES.md](https://github.com/cloudant/python-cloudant/blob/master/CHANGES.md)
-- [ ] You have completed the PR template below:
+- [ ] Tick to sign-off your agreement to the [Developer Certificate of Origin (DCO) 1.1](../blob/master/DCO1.1.txt)
+- [ ] Added tests for code changes _or_ test/build only changes
+- [ ] Updated the change log file (`CHANGES.md`|`CHANGELOG.md`) _or_ test/build only changes
+- [ ] Completed the PR template below:
 
-## What
+## Description
+<!--
+Provide a short description; saving the detail for the `Approach` section
 
-What was changed, e.g. Added support for querying views.
+Also EITHER:
+Link to issue this PR is resolving, use the Fixes #nnn form so that the
+issue closes automatically when the PR merges e.g.:
 
-## How
+Fixes #23
 
-How the change was implemented and reasoning behind it, e.g. Added create_index API to allow
-the creation of text and json indexes.
+OR
+
+For PRs without an associated issue and/or test/build issues
+
+### 1. Steps to reproduce and the simplest code sample possible to demonstrate the issue
+### 2. What you expected to happen
+### 3. What actually happened
+-->
+
+## Approach
+
+<!--
+Be brief: which component(s) of the code base does the fix focus on.
+
+A place to note whether the part of the code base that is being worked is
+particularly sensitive.
+-->
+
+## Schema & API Changes
+
+<!--
+EITHER:
+
+- "No change"
+
+OR
+
+For public API (as opposed to internal) changes
+
+- "Fixing bug in API, will change x in such-and-such way"
+-->
+
+## Security and Privacy
+
+<!--
+EITHER:
+
+- "No change"
+
+OR
+
+"Making changes in e.g. auth|https|encryption|io
+need to be careful about..."
+
+-->
 
 ## Testing
 
-How to test your changes work, not required for documentation changes.
+<!--
+EITHER:
+
+- Added new tests:
+    - test x
+    - test y
+    - test z
+
+OR
+
+- Modified existing tests because ...
+
+OR
+
+- N/A build or packaging only changes
+
+OR
+
+In exceptional circumstances there may be a good reason we can't add automated
+tests, for example if a specific device is required to reproduce a problem.
+
+- No new tests because...
+-->
+
+## Monitoring and Logging
+<!--
+EITHER:
+
+- "No change"
 
-## Issues
+OR
 
-Links to the github issue(s) (if present) that this pull request is resolving.
+- "Added new log line X..."
+-->

CONTRIBUTING.md

@@ -0,0 +1,84 @@
+# Contributing
+
+## Issues
+
+Please [read these guidelines](http://ibm.biz/cdt-issue-guide) before opening an issue.
+If you still need to open an issue then we ask that you complete the template as
+fully as possible.
+
+## Pull requests
+
+We welcome pull requests, but ask contributors to keep in mind the following:
+
+* Only PRs with the template completed will be accepted
+* We will not accept PRs for user specific functionality
+
+### Developer Certificate of Origin
+
+In order for us to accept pull-requests, the contributor must sign-off a
+[Developer Certificate of Origin (DCO)](DCO1.1.txt). This clarifies the
+intellectual property license granted with any contribution. It is for your
+protection as a Contributor as well as the protection of IBM and its customers;
+it does not change your rights to use your own Contributions for any other purpose.
+
+Please read the agreement and acknowledge it by ticking the appropriate box in the PR
+ text, for example:
+
+- [x] Tick to sign-off your agreement to the Developer Certificate of Origin (DCO) 1.1
+
+## General information
+
+Python-Cloudant Client Library is written in Python.
+
+## Requirements
+
+- Python
+- pip
+
+It is recommended to use a [virtual environment](https://virtualenv.pypa.io/en/latest) during development. The
+python-cloudant dependencies can be installed via the `requirements.txt` file using pip.
+
+For example to create a virtualenv and install requirements:
+
+```sh
+virtualenv .
+./bin/activate
+pip install -r requirements.txt
+pip install -r test-requirements.txt
+```
+
+## Testing
+
+The tests need an Apache CouchDB or Cloudant service to run against.
+
+The tests create databases in your CouchDB instance, these are `db-<uuid4()>`.
+They also create and delete documents in the `_replicator` database.
+
+The tests are run with the `nosetests` runner. In this example the `ADMIN_PARTY` environment variable is used to tell
+ the tests not to use any authentication. See below for the full set of variables that can be used.
+
+```sh
+$ ADMIN_PARTY=true nosetests -w ./tests/unit
+```
+
+There are several environment variables which affect
+test behaviour:
+
+- `RUN_CLOUDANT_TESTS`: set this to run the tests that use Cloudant-specific features. If
+  you set this, you must set one of the following combinations of other variables:
+    - `DB_URL`, `DB_USER` and `DB_PASSWORD`.
+    - `CLOUDANT_ACCOUNT`, `DB_USER` and `DB_PASSWORD`.
+    - If you set both `DB_URL` and `CLOUDANT_ACCOUNT`, `DB_URL` is used as the
+      URL to make requests to and `CLOUDANT_ACCOUNT` is inserted into the `X-Cloudant-User`
+      header.
+- Without `RUN_CLOUDANT_TESTS`, the following environment variables have an effect:
+    - Set `DB_URL` to set the root URL of the CouchDB/Cloudant instance. It defaults
+      to `http://localhost:5984`.
+    - Set `ADMIN_PARTY` to `true` to not use any authentication details.
+    - Without `ADMIN_PARTY`, set `DB_USER` and `DB_PASSWORD` to use those
+      credentials to access the database.
+    - Without `ADMIN_PARTY` and `DB_USER`, the tests assume CouchDB is in
+      admin party mode, but create a user via `_config` to run tests as.
+      This user is deleted at the end of the test run, but beware it'll
+      break other applications using the CouchDB instance that rely on
+      admin party mode being in effect while the tests are running.