Merge pull request #426 from scitran/add-general-contributing-guidelines

Add general contributing guidelines

.travis.yml

@@ -14,7 +14,6 @@ before_script:
 script:
   - bin/runtests.sh unit --ci
   - bin/runtests.sh integration --ci
-# Disable Refactor and Convention reports
-  - pylint --disable=C,R api
+  - ./test/lint.sh api
 after_success:
   - coveralls

CONTRIBUTING.md

-### Design resource
-1. Begin by writing a description of your API resource and it’s business functionality
-2. Choose a name for your resource that describes what it does
-3. Create a url from the name.  If your resource is a collection and the name is a noun, pluralize the name e.g. “uploads”
+## Contributing
+1. Contributions should follow the "Code Standards" section of this document.
+1. If adding an endpoint or resource to the API, also follow "Adding an API Resource".
+1. Follow commit message guidelines.
+1. Use `git rebase [-i]` to clean up your contribution and resolve pending merge conflicts.
+1. Submit a pull request and ensure that CI passes.
 
-### Add RAML for API endpoints
-1. Create a new resource file, called <resource_name>.raml   e.g. “uploads.raml”.  Create this file in the resources raml/resources directory
-2. In api.raml, add a line with the URL of your resource and an include directive for your resource raml file.  E.g.   “/uploads: !include resources/uploads.raml”
-3. In your resource file, define your resource.  Begin by adding a “description” property with the description you wrote in step 1
-4. Add example properties for both request and response.  Examples should be stored in the examples/ directory, for example core/raml/examples/request/uploads.json 
-5. Use http://jsonschema.net/#/  to generate jsonschema for both request and response body.  Edit jsonschema as necessary.  Before generating your schema, scroll down and uncheck “allow additional properties”  Schemas are stored in the “schemas” folder, for example core/raml/schemas/input/uploads.json   
 
-### [Testing](https://github.com/scitran/core/blob/master/TESTING.md) - Click here
+## Code Standards
+### Docstrings
+- Use [Google Style Docstrings](http://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html).
+- Add docstrings to all functions with a one-line description of its purpose.
 
+### Format
+Ensure that `./test/lint.sh api` exists without errors.
+
+
+## Adding an API Resource
+### Design Resource
+1. Write a description of your API resource and its business functionality.
+1. Choose a descriptive name for your resource that aligns with existing names.
+1. Create a URL from the name. If your resource is a collection, the name should be a pluralized noun, e.g., "files".
+
+### Add RAML for API Endpoints
+1. Create a new resource file, called `<resource_name>.raml`, e.g., `files.raml`. Create this file in the `raml/resources` directory.
+1. In `api.raml`, add a line with the URL of your resource and an include directive for your resource raml file, e.g., `/files: !include resources/files.raml`.
+1. In your resource file, define your resource. Begin by adding a `description` property with the description you wrote in step 1.
+1. Add example properties for both request and response. Examples should be stored in the `examples/` directory, e.g., `raml/examples/request/files.json`.
+1. Use [JSONSchema.net](http://jsonschema.net/) to generate a JSON schema for both request and response body. Edit the schema as necessary. Before generating your schema, scroll down and uncheck "allow additional properties".  Schemas are stored in the `schemas/` directory, e.g., `raml/schemas/input/files.json`.
+
+### Testing
+Follow the procedures outlined in our [testing instructions](https://github.com/scitran/core/blob/master/TESTING.md).

bin/runtests.sh

@@ -77,7 +77,12 @@ case "$1-$2" in
       run \
       --rm \
       --entrypoint "newman run /usr/src/tests/postman/integration_tests.postman_collection -e /usr/src/tests/postman/environments/travis-ci.postman_environment" \
-      integration-test ||
+      integration-test &&
+    echo "Checking number of files with DOS encoding:" &&
+    ! find * -type f -exec file {} \; | \
+      grep -I "with CRLF line terminators" &&
+    echo "Checking for files with windows style newline:" &&
+    ! grep -rI $'\r' * ||
     # set failure exit code in the event any previous commands in chain failed.
     exit_code=1
 

test/lint.sh

+#!/usr/bin/env bash
+
+set -eu
+
+unset CDPATH
+cd "$( dirname "${BASH_SOURCE[0]}" )/.."
+
+echo "Running pylint ..."
+# TODO: Enable Refactor and Convention reports
+pylint --reports=no --disable=C,R "$@"
+
+#echo
+#
+#echo "Running pep8 ..."
+#pep8 --max-line-length=150 --ignore=E402 "$@"