contribute.md

Contribute to the samples

As of January 2021, this repo is no longer being actively maintained. It no longer accepts contributions. This document remains to explain how the samples are laid out.

Organization and style

1. Samples for an API area should live together under the samples package. Each module is an area.

   |-- src
       |-- samples
           |-- git.py
   

2. Within a module, create a method for each sample. Samples are not object-oriented.

   • The name of the method should represent what the sample is demonstrating, e.g. get_{resource}:

   def get_repos(...):

   • The method must accept a context parameter, which will contain information passed in from the sample runner infrastructure:

   def get_repos(context):

   • The method must decorated with @resource('resource_name') to be detected:

   from samples import resource
   
   @resource('repositories')
   def get_repos(context):

   • Results should be logged using the utils.emit function:

   from samples import resource
   from utils import emit, find_any_project
   
   @resource('repositories')
   def get_repos(context):
       project = find_any_project(context)
   
       git_client = context.connection.clients.get_git_client()
   
       repos = git_client.get_repositories(project.id)
       for repo in repos:
           emit(repo)
   
       return repos

3. Coding and style

   • Samples should show catching exceptions for APIs where exceptions are common
   • Use line breaks and empty lines to help delineate important sections or lines that need to stand out
   • Use the same "dummy" data across all samples so it's easier to correlate similar concepts
   • Be as Pythonic and PEP8-y as you can be without violating the above principles. flake8 is your friend, and should run without anything triggering. (Non-standard default: 120-character lines are allowed.)

4. All samples MUST be runnable on their own without any input

5. All samples SHOULD clean up after themselves. Have a sample method create a resource (to demonstrate creation). Have a later sample method delete the previously created resource. In between the creation and deletion, you can show updating the resource (if applicable)

Tests

You can run pip install -r requirements.dev.txt && pytest to run tests. They should all pass.