Skip to content

Latest commit

 

History

History
55 lines (42 loc) · 2.84 KB

CONTRIBUTING.md

File metadata and controls

55 lines (42 loc) · 2.84 KB
Raw

Contributing

  1. Contributions should follow the "Code Standards" section of this document.
  2. If adding an endpoint or resource to the API, also follow "Adding an API Resource".
  3. Follow commit message guidelines.
  4. Use git rebase [-i] to clean up your contribution and resolve pending merge conflicts.
  5. Submit a pull request and ensure that CI passes.

Upgrading Python Packages

List outdated packages

pip list --local --outdated

Then review and decide what upgrades to make, if any. Changes to requirements.txt should always be by pull request.

Code Standards

Testing

  • Add tests for every change made
  • Tests should be realistic and exercise a wide range of possibilities

Docstrings

Format

Ensure that ./tests/bin/run-tests-docker.sh -- -l exits without errors.

Commit Messages

  1. The subject line should be a phrase describing the commit and limited to 50 characters
  2. The subject line should be as specific as possible, e.g. "Add new API resource for user API keys", rather than "Update authentication".

Adding an API Resource

Design Resource

  1. Write a description of your API resource and its business functionality.
  2. Choose a descriptive name for your resource that aligns with existing names.
  3. Create a URL from the name. If your resource is a collection, the name should be a pluralized noun, e.g., "files".

Quality Standards

  1. All API resources must have input validation
  2. New API resources should follow the error handling convention and raise webapp2.HTTPException

Add Swagger for API Endpoints

  1. Create a new resource file, called <resource_name>.yaml, e.g., files.yaml. Create this file in the swagger/paths directory.
  2. In index.yaml, add an $include line for your resource file, e.g., - paths/files.yaml.
  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, e.g., swagger/examples/request/files.json.
  5. Use 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., swagger/schemas/input/files.json.
  6. Verify that the example properties pass schema validation by running the unit tests. New schemas and examples will be tested automatically. (See testing instructions below)

Testing

Follow the procedures outlined in our testing instructions.