Template updates (#434)

* Updated issue and PR templates
* Updated CONTRIBUTING information

.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.
 
-- CDTDatastore version(s) that are affected by this 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
 - iOS/macOS version
-- A small code sample that demonstrates the issue.
+    > macOS 10.13.1
+-->

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,24 +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/CDTDatastore/blob/master/DCO1.1.txt)
-- [ ] You have added tests for any code changes
-- [ ] You have updated the [CHANGELOG.md](https://github.com/cloudant/CDTDatastore/blob/master/CHANGELOG.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.
->Fix bug for handling queries like { "$not" : { "$size" : 1} }.
+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 recursion logic to handle size operator in negated clause.
+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

@@ -1,6 +1,19 @@
-# Contributing to CDTDatastore
+# Contributing
 
-## Developer Certificate of Origin
+## 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
@@ -13,56 +26,9 @@ Please read the agreement and acknowledge it by ticking the appropriate box in t
 
 - [x] Tick to sign-off your agreement to the Developer Certificate of Origin (DCO) 1.1
 
-## Setting up your environment
+## General information
 
-You have probably got most of these set up already, but starting from scratch
-you'll need:
-
-* Xcode
-* Xcode command line tools
-* Cocoapods (minimum version 1.0.0 beta 2)
-* Homebrew (optional, but useful)
-* xcpretty (optional)
-
-First, download Xcode from the app store or [ADC][adc].
-
-When this is installed, install the command line tools. The simplest way is:
-
-```bash
-xcode-select --install
-```
-
-Install homebrew using the [guide on the homebrew site][homebrew].
-
-Install cocoapods using the [guide on their site][cpinstall].
-
-Note that we currently require a pre-release version of cocoapods, so
-your install options will look something like this:
-
-```bash
-sudo gem install cocoapods --pre
-```
-
-Finally, if you want to build from the command line, install [xcpretty][xcpretty],
-which makes the `xcodebuild` output more readable.
-
-It's a gem:
-
-```bash
-sudo gem install xcpretty
-```
-
-[adc]: http://developer.apple.com/
-[xcpretty]: https://github.com/mneorr/XCPretty
-[homebrew]: http://brew.sh
-[cpinstall]: http://guides.cocoapods.org/using/index.html
-
-## Coding guidelines
-
-The house style is [documented](doc/style-guide.md). There's information there on using
-`clang-format` to automatically use the right format.
-
-## Getting started with the project
+### Getting started with the project
 
 The main workspace is `CDTDatastore.xcworkspace` in the root of the
 checkout. This contains everything needed to develop and test the
@@ -132,6 +98,76 @@ First, make sure you add them to the right group within the `CDTDatastore` group
 When adding files to the workspace, make sure to keep the groups in the
 workspace up to date with the file locations on the file system.
 
+### Coding guidelines
+
+The house style is [documented](doc/style-guide.md). There's information there on using
+`clang-format` to automatically use the right format.
+
+## Requirements
+
+### Setting up your environment
+
+You have probably got most of these set up already, but starting from scratch
+you'll need:
+
+* Xcode
+* Xcode command line tools
+* Cocoapods (minimum version 1.0.0 beta 2)
+* Homebrew (optional, but useful)
+* xcpretty (optional)
+
+First, download Xcode from the app store or [ADC][adc].
+
+When this is installed, install the command line tools. The simplest way is:
+
+```bash
+xcode-select --install
+```
+
+Install homebrew using the [guide on the homebrew site][homebrew].
+
+Install cocoapods using the [guide on their site][cpinstall].
+
+Note that we currently require a pre-release version of cocoapods, so
+your install options will look something like this:
+
+```bash
+sudo gem install cocoapods --pre
+```
+
+Finally, if you want to build from the command line, install [xcpretty][xcpretty],
+which makes the `xcodebuild` output more readable.
+
+It's a gem:
+
+```bash
+sudo gem install xcpretty
+```
+
+[adc]: http://developer.apple.com/
+[xcpretty]: https://github.com/mneorr/XCPretty
+[homebrew]: http://brew.sh
+[cpinstall]: http://guides.cocoapods.org/using/index.html
+
+## Building
+
+### With Encryption
+
+Add the `ENCRYPT_DATABASE=1` environment variable.
+
+### Documentation
+
+Install [appledocs][appledocs].
+
+Use `rake docs` to build the docs and install into Xcode.
+
+As the `appledocs` docs themselves are down, here's a
+[good introduction to the format](http://www.cocoanetics.com/2011/11/amazing-apple-like-documentation/).
+
+[appledocs]: http://gentlebytes.com/appledoc/
+
+## Testing
+
 ### Tests and encryption tests
 
 It is possible to combine `CDTDatastore` with [SQLCipher][SQLCipher] to generate
@@ -153,17 +189,6 @@ to run the tests with encryption support, use the rakefile.
 [FMDB]: https://github.com/ccgus/fmdb
 [CDTEncryptionKeyProvider]: Classes/common/Encryption/CDTEncryptionKeyProvider.h
 
-### Documentation
-
-Install [appledocs][appledocs].
-
-Use `rake docs` to build the docs and install into Xcode.
-
-As the `appledocs` docs themselves are down, here's a
-[good introduction to the format](http://www.cocoanetics.com/2011/11/amazing-apple-like-documentation/).
-
-[appledocs]: http://gentlebytes.com/appledoc/
-
 ### Using xcodebuild and xcpretty to run the tests
 
 Run the following at the command line:
@@ -209,7 +234,6 @@ Environment Variable | Purpose | Default
 `TEST_COUCH_USERNAME` | CouchDB account username |
 `TEST_COUCH_PASSWORD` | CouchDB account Password |
 
-
 Example
 
 ```bash
@@ -222,18 +246,3 @@ $ export TEST_COUCH_PASSWORD=apassword
 $ xcodebuild -workspace ReplicationAcceptance.xcworkspace -scheme RA_Tests_OSX -destination 'platform=OS X' test | xcpretty
 
 ```
-
-## Contributing your changes
-
-We follow a fairly standard procedure:
-
-* Fork the CDTDatastore repo into your own account, clone to your machine.
-* Create a branch with your changes on (`git checkout -b my-new-feature`)
-  * Make sure to update the CHANGELOG and CONTRIBUTORS before sending a PR.
-  * All contributions must include tests.
-  * Try to follow the style of the code around the code you
-    are adding -- the project contains source code from a few places with
-    slightly differing styles.
-* Commit your changes (`git commit -am 'Add some feature'`)
-* Push to the branch (`git push origin my-new-feature`)
-* Issue a PR for this to our repo.